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xclipboard(lx), xclock(lx), xcmsdb(lx), xcon-sole(lx), xcutsel(lx), xdm(lx), xdpylnfo(lx), xf86config(lx), 
xfd(lx), xfs(lx), xhost(lx), xlnit(lx), xkill(lx), xlogo(lx), xlsatoms(lx), xlsclients(lx), xlsfonts(lx), 
xmag(lx), xmkmf(lx), xmodmap(lx), xon(lx), xprop(lx), xrdb(lx), xrefresh(lx), xset(lx), xsetroot(lx), xsm(lx), 
xsmciient(lx), xstdcmap(lx), xterm(lx), xwd(lx), xwininfo(lx), xwud(lx) copyright © 1993,1994 X Consor¬ 
tium. 

portmap(8) copyright © 1987 Sun M icrosystems copyright © 1990,1991 The Regents of the University of 
California. 

rpcgen.new(l) copyright © 1988,1990 Sun M icrosystems, Inc. 
rstart(lx), rstartd(lx) copyright © 1993 Q uarterdeck Office Systems 
showmount(8) copyright 1993 Rick Sladkey (jrs@worid.std.com). 

twm(lx) copyright © 1993,1994 X Consortium. Portions copyright 1988 Evans& Sutherland Computer 
Corporation. Portions copyright 1989 H ewIett-Packard Company, 
xieperf. i x copyright 1993,1994 by AG E Logic, I nc. 

M any thanks to all these contributors for providing excellent-quality man pages and also to the Free Software 
Foundation for providing the rest. 
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Introduction 

This section introduces and describes user commands. 

AUTHORS 

Look at the header of the manual page for the author(s) and copyright conditions Note that these can be different from page 
to page. 

addftinfo 

addftinfo— Add information totroff font files for use with groff 

SYNOPSIS 

addftinfo [ -paramvalue... ] res unitwidth font 

DESCRIPTION 

addftinfo readsatroff font file and adds some additional font-metric information that is used by thegroff system. The font 
file with the information added is written on the standard output. The information added isguessed using some parametric 
information about the font and assumptions about the traditional troff namesfor characters. The main information added 
is the heights and depths of characters The res and unitwidth arguments should be the same as the corresponding param¬ 
eters in the desc file; font isthename of thefile describing thefont; if font ends with I, thefontwill be assumed to be italic. 

OPTIONS 

Each of the f options changes one of the parameters that is used to derive the heights and depths. Like the existing quantities 

in thefontfile, each value isin inche^resforafont whose point size isumtwidth. param must be one of the following: 

x ■ height T he height of lowercase letters without ascenders such as x 

fig-height The height of figures (digits) 

asc-height The height of characters with ascenders, such asb, d, or I 

body-height The height of characters such as parentheses 

cap-height T he height of uppercase letters such as A 

comma-depth The depth of a comma 

desc-depth The depth of characters with descenders, such asp, q, or y 

body-depth The depth of characters such as parentheses 

addftinfo makes no attempt to use the specified parameters to guess the unspecified parameters If a parameter is not 
specified, the default will be used. The defaults are chosen to have the reasonable values for a Times font. 

SEE ALSO 

font(5) groff_font(5), groff(1), groff_char(7) 

Groff Version 1.09, 6 August 1992 


afmtodit 

afmtodit-Createfontfilesforusewith groff -Tps 

SYNOPSIS 

afmtodit [ -ns ] [-ddesc _f i I e ] [-ee n c _f i I e ] [-in ] [-an ] afm.file mapjile font 



afmtodit 


m 

DESCRIPTION 

afmtodit creates a font file for use with groff andgrops. afmtodit is written in Perl; you must have Perl version 3 installed in 
order to run afmtodit. afm_fiie istheAFM (Adobe Font M etric) file for thefont. map_fiie is a file that says which groff 
character names map onto each PostScript character name; this file should contain a sequence of lines of the form: 

where ps_char isthe PostScript name of the character and groff_char isthe groff name of the character (as used in the groff 
font file) The same ps_char can occur multiple times in thefile each groff_char must occur, at most, once, font isthe groff 
name of thefont. If a PostScript character is in the encoding to be used for thefont but is not mentioned in map_f lie, then 
afmtodit will put it in the groff font file asan unnamed character, which can be accessed by the \n escape sequence in troff. 
Thegroff_font file will be output to a file called font. 

If there is a downloadable font filefor thefont, it may be listed in thefile/usr/iib/groff/font/devps/downioad; see grops(l). 

If the -i option is used, afmtodit will automatically generate an italic correction, a left italic correction, and a subscript 

correction for each character (the significance of these parameters is explained in groff_font(5)); these parameters may be 

specified for individual characters by adding to the afm_ftie lines of theform: 

italicCorrectionps charn 

leftltalicCorrectionps charn 

subscriptCorrectionps charn 

where ps_char isthe PostScript name of the character, and n isthedesired value of the corresponding parameter in thou¬ 
sandths of an em. These parameters are normally needed only for italic (or oblique) fonts. 

OPTIONS 

-n D on't output a ligatures command for thisfont. Use this with constant-width fonts 

-s Thefont is special. The effect of this option is to add the special command to thefont file. 

-ddesc_f i i e The devicedescription file is des c.f i i e rather than the default desc. 

-ee nc _f i i e The PostScript font should be reencoded to use the encoding described in enc.fi i e. Theformat of 

enc.file isdescribed in grops(l). 

-an Usen astheslant parameter in thefont file; this is used by groff in the positioning of accents By 

default, afmtodit uses the negative of the itaiicAngie specified in theafm.fi i e; with true italic 
fonts, it issometimes desirable to use a slant that is less than this. If you find that characters from 
an italic font have accents placed too far to the right over them, then use the-a option to give the 
font a smaller slant. 

-in G enerate an italic correction for each character so that the character's width plus the character's 

italic correction isequal to n thousandths of an em plus the amount by which the right edge of the 
character's bounding isto the right of the character's origin. If this would result in a negative italic 
correction, use a zero italic correction instead. 

Also generate a subscript correction equal to the product of the tangent of the slant of thefont and 
four-fifths of the x-height of thefont. If this would result in a subscript correction greater than the 
italic correction, use a subscript correction equal to the italic correction instead. 

Also generate a left italic correction for each character equal to n thousandths of an em plus the 
amount by which the left edge of the character's bounding box is to the left of the character's 
origin. The left italic correction may be negative. 

This option is normally needed only with italic (or oblique) fonts The font files distributed with 
groff were created using an option of -iso for italic fonts 

FILES 

/usr/lib/groff/font/devps/DESC 
/usr/lib/groff/font/devps/F 
/usr/lib/groff/font/devps/download 


Device description file 
Font description filefor font f 
L ist of downloadable fonts 
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/usr/nb/groff/font/devps/text. enc Encoding used for text fonts 

/usr/lib/groff/font/devps/generate/textmap Standard mapping 

SEE ALSO 

groff(l), grops(l), groff_font(5), perl(l) 

GroffVersion 1.09,14 February 1994 


ansi2knr 

anst2knr—Convert ANSI C to Kernighan & RitchieC 

SYNOPSIS 

ansi2knr i n p u t _ f i I e outputjile 

DESCRIPTION 

If no out put _f i i e is supplied, output goes to stdout. T here are no error messages 

ansi2knr recognizes functions by seeing a nonkeyword identifier at the left margin, followed by a left parenthesis with aright 
parenthesis as the last character on the line. It will recognize a multiline header if the last character on each line but the last is 
a left parenthesis or comma. These algorithms ignore whitespace and comments except that the function name must be the 
first thing on the line. 

The following constructs will confuse it: 

■ Any other construct that starts at the left margin and follows the above syntax (such as a macro or function call) 

■ M acrosthattinkerwith the syntax of the function header 

31 December 1990 


anytopnm 

anytopnm—Attempt to convert an unknown type of image file to a portable anymap 

SYNOPSIS 

anytopnm file 

DESCRIPTION 

anytopnm usesthefile program, possibly augmented by the magic numbers file included with pbmplus, to try to figure out 
what type of image file it is If that fails (very few image formats have magic numbers), looks at the filename extension. If 
that fails, punt. 

T he type of the output file depends on the input file 

SEE ALSO 

pnmfile(l), pnm(5), file(l) 

BUGS 

It'sascript. Scripts are not portable to non-UN IX environments 

AUTHOR 

Copyright © 1991 byJef Poskanzer 


27 July 1990 




m 


appres 

appres— List x application resource database 

SYNOPSIS 

appres [[class [instance]] [-1] [t ool ki t opt i ons ] 

DESCRIPTION 

The appres program prints the resources seen by an application (or subhierarchy of an application) with the specified class 
and instance names. It can be used to determine which resources a particular program will load. For example, 

% appres XTerm 

will list the resources that any xterm program will load. If no application class is specified, the class -AppResTest- is used. 

To match a particular instance name specify an instance name explicitly after the class name or use the normal xt toolkit 
option. For example 

% appres XTerm myxterm 

or 

% appres XTerm -name myxterm 

To list resourcesthat match a subhierarchy of an application, specify hierarchical class and instance names. The number of 
class and instance components must be equal, and theinstance name should not be specified with a toolkit option. For 
example, 

% appres Xman.TopLevelShell.Form xman.topBox.form 

will list the resources of widgets of xman topBox hierarchy. To list just the resources matching a specific level in the hierarchy, 
usethe-i option. For example, 

% appres XTerm.VT100 xterm.vt100 -1 

will list the resources matching the xterm vtio 0 widget. 

SEE ALSO 

X(l), xrdb(l), listres(l) 

AUTHOR 

Jim Fulton (M IT X Consortium) 

X Version 11 Release 6 


ar 

ar— C reate, modify, and extract from archives 

SYNOPSIS 

ar [ ■ ] dmpqrtx[abcilosuvV] [ membername ] archive files ... 

DESCRIPTION 

TheGN U ar program creates, modifies, and extracts from archives An archive is a single file holding a collection of other 
filesin a structure that makes it possible to retrieve the original individual files (called members of the archive). 
Theoriginal files' contents, mode (permissions), timestamp, owner, and group are preserved in the archive and may be 
reconstituted on extraction. 
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GNU ar can maintain archives whose members have names of any length; however, depending on how ar is configured on 
your system, a limit on member-name length may be imposed (for compatibility with archive formats maintained with other 
tools). If it exists, the limit is often 15 characters (typical of formats related to a. out) or 16 characters (typical of formats 
related to coff). 

ar is considered a binary utility because archives of this sort are most often used as libraries holding commonly needed 
subroutines 

ar will create an index to the symbols defined in relocatable object modules in the archive when you specify the modifiers. 
Once created, this index is updated in the archive whenever ar makes a change to its contents (save for the q update 
operation). An archive with such an index speeds up linking to the library, and allows routines in the library to call each 
other without regard to their placement in the archive. 

You may use™ -s or™ -print-armapto list thisindex table. If an archive lacks thetable, another form of ar called raniib 
can be used to add just thetable. 

ar insists on at least two arguments to execute: one keyletter specifying the operation (optionally accompanied by other 
keyletters specifying modifiers), and the archive name to acton. 

M ost operations can also accept further files arguments, specifying particular files to operate on. 

OPTIONS 

GN U ar allows you to mix the operation codep and modifier flags mod in any order, within the first command-line 
argument. 

If you wish, you may begin the first command-line argument with a dash. 

T he p keyletter specifies what operation to execute: it may be any of the followi ng, but you must specify only one of them: 
d Delete modules from the archive Specify the names of modules to bedeieted as files; the archive is 

untouched if you specify no files to delete. 

If you specify the v modifier, ar will list each module as it is deleted, 
m Use this operation to move members in an archive 

Theordering of members in an archive can make a difference in how programs are linked using the 
library if a symbol is defined in more than one member. 

If no modifiers are used with m, any members you name in thefiles arguments are moved to the end of 
the archive; you can use the a, b, or i modifiers to move them to a specified place instead, 
p Print the specified members of the archive to the standard output file. If thev modifier isspecified, 

show the membername before copying its contents to standard output. 

If you specify no files, all thefiles in the archive are printed, 
q Quick append; add files to the end of archive without checking for replacement. 

The modifiers a, b, and ido not affect this operation; new members are always placed at the end of the 
archive. 

T he modifier v makes ar list each file as it is appended. 

Since the point of this operation is speed, the archive's symbol table index is not updated, even if it 
already existed; you can use ar s or raniib explicitly to update thesymbol table index, 
r Insert files into archive (with replacement). This operation differs from q in that any previously existing 

members are deleted if their names match those being added. 

If one of thefiles named in files doesn't exist, ar displays an error message and leaves undisturbed any 
existing members of the archive matching that name 

By default, new members are added at the end of thefile, but you may use one of the modifiers a, b, or 
i to request placement relative to some existing member. 

T he modifier v used with this operation elicits a line of output for each file inserted, along with one of 
the letters a or r to indicate whether thefile was appended (no old member deleted) or replaced. 



sr □ 

t Display a table listing the contents of archive or those of the files listed in files that are present in the 

archive. N ormally, only the membername is shown; if you also want to see the modes (permissions), 
timestamp, owner, group, and size you can request that by also specifying thev modifier. 

If you do not specify any files, all files in the archive are listed. 

If there is more than one file with the same name (say, fie) in an archive (say, b. a), ar t b.a fie will 
list only thefirst instance to see them all, you must ask for a complete listing-in our example, ar t 

x Extract members (named files) from the archive. You can use thev modifier with this operation to 

request that ar list each name as it extracts it. 

If you do not specify any files, all files in the archive are extracted. 

A number of modifiers (mod) may immediately follow the p keyletter, to specify variations on an operation's behavior, as 
follows: 

a Add new files after an existing member of the archive. If you use the modifier a, the name of an 

existing archive member must be present as the membername argument, before thearchive specifica¬ 
tion. 

b Add new files before an existing member of thearchive. If you use the modifier b, the name of an 

existing archive member must be present as the membername argument, before thearchive specifica¬ 
tion (same as i). 

c Create the archive The specified archive is always created if it didn't exist when you request an update. 

But a warning isissued unless you specify in advance that you expect to create it by using this modifier, 
i Insert new files before an existing member of thearchive Ifyou use the modifier i, the name of an 

existing archive member must be present as the membername argument, before thearchive specifica¬ 
tion. (same as b). 

1 This modifier is accepted but not used. 

o Preserve theoriginal dates of members when extracting them. Ifyou do not specify this modifier, files 

extracted from thearchive will be stamped with the time of extraction, 
s W rite an object-file index into the archive or update an existing one, even if no other change is made 

to thearchive. You may use this modifier flag either with any operation, or alone Running ar s on an 
archiveisequivalent to running ramib on it. 

u Normally, ar r... inserts all files listed into the archive. If you would like to insert only those of the 

fi les you list that are newer than existing members of the same names, use this modifier. T he u modifier 
is allowed only for the operation r (replace). In particular, the combi nation qu is not allowed, since 
checking thetimestamps would lose any speed advantage from the operation q. 
v This modifier requests the verbose version of an operation. M any operations display additional 

information, such as filenames processed, when the modifier v isappended. 
v This modifier shows the version number of ar. 

SEE ALSO 

binutiis entry in info; TheGNU BinaryU tilities, Roland H. Pesch (October 1991); nm(l), amib(l) 

COPYING 

Copyright © 1991 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided the copyright notice and this permission notice are preserved on all copies Permission isgranted to copy 
and distribute modified versionsof this manual under the conditionsfor verbatim copying, provided that the entire resulting 
derived work is distributed under thetermsof a permission notice identical to thisone. 

Permission isgranted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in theoriginal English. 


CygnusSupport, 5 N ovember!991 
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arch 

arch— Print architecture 

SYNOPSIS 

DESCRIPTION 

arch displays machine architecture type. 

SEE ALSO 

uname(l), uname(2) 

Debian GNU/Linux, 15 January 1994 


GNU as 

GNU as—TheportableGNU assembler 

SYNOPSIS 

as [ -a | -al j -as ][-D ][-f ][-I path ] [-K ][-L ] [-o obj f i I e ][-R ] [-v JJ-w ][-\|\ 
files ...] 

i960-only options 

[ -ACA] -ACA A ! -ACB | -ACC| -AKA| -AKB ] -AKC| -AMC][-b ][-no-relax ] 

m680x0-only options 

[ -1 ][-mc68000| -mc68010| -mc68020] 

DESCRIPTION 

GNU as is really a family of assemblers. If you use (or have used) theGNU assembler on one architecture, you should find a 
fairly similar environment when you use it on another architecture. Each version hasmuch in common with theothers 
including object file formats, most assembler directives (often called pseudo-ops) and assembler syntax. 

For information on the syntax and pseudo-ops used by GNU as, see as entry in info (or the manual UsngasTheGNU 
Assembler). 

as is primarily intended to assemble the output of theGN U C compiler gcc for use by the linker id. Nevertheless, we've tried 
to make as assemble correctly everything that the native assembler would. This doesn't mean as always uses the same syntax 
as another assembler for the same architecture; for example, we know of several incompatible versions of 680x0 assembly 
language syntax. 

Each time you run as, it assembles exactly one source program. The source program is made up of one or more files (The 
standard input is also a file.) 

If as isgiven no filenames it attempts to read one input filefrom the as standard input, which is normally your terminal. 
You may havetotypeCtrl-D to tell as thereisno more program to assemble. U se — if you need to explicitly name the 
standard input file in your command line. 

as may write warnings and error messages to the standard error file (usually your terminal). This should not happen when as 
is run automatically by a compiler. Warnings report an assumption made so that as could keep assembling a flawed program; 
errors report a grave problem that stops the assembly. 
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OPTIONS 

-a|-al|-as 


-I\pat h 




—\! \f i I e s... 


-mc68000|-mc68010 \ -mc68020 


Turn on assembly listings; -ai, listing only, -as, symbolsonly, -a, everything. 

This option is accepted only for script compatibility with calls to other assemblers; it 
has no effect on as. 

"Fast"-skip preprocessing (assume source iscompiler output). 

Add path to the search list for .include directives. 

Issue warnings when difference tables altered for long displacements. 

Keep (in symbol table) local symbols, starting with L. 

Name the object-file output from as. 

Fold data section into text section. 

Announce as version. 

Suppress warning messages 

Source files to assemble or standard input (-). 

(When configured for Intel 960.) Specify which variant of the 960 architecture isthe 
target. 

(W hen configured for I ntel 960.) Add code to collect statistics about branches taken. 
(W hen configured for Intel 960.) Do not alter compare-and-branch instructionsfor 
long displacements; error if necessary. 

(W hen configured for M otorola 68000.) Shorten references to undefined symbols to 
one word instead of two. 

(W hen configured for M otorola 68000.) Specify which processor in the 68000 
family is the target (default 68020). 


Options may be in any order, and may be before, after, or between filenames. The order of filenames issignificant. 

The double hyphens command (-) by itself names the standard input file explicitly, asoneofthefilesforasto assemble. 
Except for —, any command line argument that begins with a hyphen (-) isan option. Each option changes the behavior of 
as. No option changes the way another option works An option isa hyphen followed by one or more letters thecaseofthe 
letter isimportant. All options are optional. 

The-0 option expects exactly onefilename to follow. The filenamemay either immediately follow the option's letter 
(compatible with older assemblers) or it may be the next command argument (GNU standard). 

T hese two command lines are equivalent: 

as -0 my-object-file.o mumble.s 


as -omy-object-file.o mumble.s 

SEE ALSO 

as entry in info] Using as TheGNU Assembler; gcc(l), id(l). 

COPYING 

Copyright © 1991,1992 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of 
this manual provided the copyright notice and this permission notice are preserved on all copies Permission is granted to 
copy and distribute modified versions of this manual under the conditionsfor verbatim copying, provided that theentire 
resulting derived work isdistributed under the terms of a permission notice identical tothisone 
Permission isgranted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in theoriginal English. 


CygnusSupport, 21 January 1992 
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asciitopgm 

asciitopgm— Convert ASCII graphics into a portable graymap 

SYNOPSIS 

asciitopgm [-d divisor] height width [asciifile] 

DESCRIPTION 

Reads ASC11 dataasinput. Produces a portable graymap with pixel values that are an approximation of the brightness of the 
ASCII characters, assuming black-on-white printing. In other words, a capital M is very dark, a period is very light, and a 
space is white. Input lines that are fewer than wi dth characters are automatically padded with spaces. 

The divisor argument is a floating-point number by which the output pixels are divided; the default value isi .0. This can be 
used to adjust the brightness of the graymap; for example, if the image istoo dim, reduce the divisor. 

In keeping with (I believe) FORTRAN line-printer conventions, input lines beginning with a + (plus) character are assumed 
to overstrike the previous line allowing a larger range of gray values. 

Thistool contradicts the message in the pbmtoascii manual: "Notethatthereisnoasciitopbmtool—thistransformation is 
oneway." 

BUGS 

The table of ASC I l-to-gray values is subject to interpretation, and, of course depends on the typeface intended for the input. 

SEE ALSO 

pbmtoascii(l), pgm(5) 

AUTHOR 

Wilson FI . Bent, Jr. (whb@usc.edu) 

26 December 1994 


atktopbm 

atktopbm— C onvert Andrew Toolkit raster object to portable bitmap 

SYNOPSIS 

atktopbm [at kfiI e ] 

DESCRIPTION 

atktopbm reads an Andrew T oolkit raster object as input and produces a portable bitmap as output. 

SEE ALSO 

pbmtoatk(l), pbm(5) 

AUTHOR 

Copyright © 1991 by Bill Janssen 


26 September 1991 
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bash—GNU Bourne-again shell 

SYNOPSIS 

bash [options] [file] 

DESCRIPTION 

bash is an sh-compatible command language interpreter that executes commands read from the standard input or from a file, 
bash also incorporates useful features from theKorn and C shells (ksh and csh). 

bash is ultimately intended to be a conformant implementation of the IEEE POSIX Shell and Tools specification (IEEE 
Working Group 10032). 

OPTIONS 

In addition to the single-character shell options documented in the description of the set built-in command, bash interprets 
the following flags when itisinvoked: 

-c s t r i n g If the -c flag is present, then commands are read from st r i ng . If there are arguments after the 

string, they are assigned to the positional parameters, starting with $0. 

-i If the-i flag is present, the shell is interactive 

-s If the -s flag is present, or if no arguments remain after option processing, then commands are 

read from the standard input. This option allows the positional parameters to beset when 
invoking an interactive shell. 

A single - signals the end of options and disables further option processing. Any arguments after 
the - are treated as filenames and arguments An argument of - is equivalent to an argument 
of-. 


bash also interprets a number of multicharacter options. T 0 be recognized, these options must appear on the command line 
before the single-character options 


-version 


-nobraceexpansion 

-nolineediting 


Do notread and execute the personal initialization file'/.bashrc if the shell is interactive. This 
option is on by default if the shell isinvoked assh. 

D 0 not read either the system-wide startup file /etc/prof iie or any of the personal initializa¬ 
tion files '/.bash_profiie, 7.bash_iogin, or '/.profile. By default, bash normally reads these 
files when it isinvoked as a login shell. (See the "Invocation" section, later in this manual page.) 
Execute commands from file instead of the standard personal initialization file 7 .bashrc, if the 
shell is interactive. (See "Invocation.") 

Show the version number of thisinstance of bash when starting. 

Do not be verbose when starting up (do not show the shell version or any other information). 
This is the default. 

M ake bash act asif it had been invoked asa login shell. 

Do not perform curly brace expansion. (See "Brace Expansion," later in this manual page.) 

Do notusetheGNU readiine library to read command lines if interactive 
Change the behavior of bash where the default operation differs from the POSIX 1003.2 
standard to match the standard. 


ARGUMENTS 

If arguments remain after option processing, and neither the-c nor the-s option has been supplied, thefirst argument is 
assumed to be the name of a file containing shell commands. If bash isinvoked in this fashion, issetto the name of thefile, 
and the positional parameters are set to the remaining arguments bash reads and executes commands from thisfile, then 
exits bash'sexit status istheexit status of the last command executed in the script. 



Parti: User Commands 


m 


DEFINITIONS 

blank 

word 

name 

meta character 


A space or tab. 

A sequence of characters considered as a single unit by the shei I. Also known as a token. 

A word consisting only of alphanumeric characters and underscores and beginning with an 
alphabetic character or an underscore. Also referred to as an identifier. 

A character that, when unquoted, separates words. One of the following: 


control operator A token that performs a control function. It is one of the following symbols: 

&, & & ,(,), |, <newline> 

RESERVED WORDS 

Reserved words are words that have a special meaning to the shell. The following words are recognized as reserved when 
unquoted and either the first word of a simple command (see "Shell Grammar," next) or the third word of a case or for 
command: 

! case do done elif else esac fl for function if in select then until while { } 


SHELL GRAM MAR 
SIMPLE COMMANDS 

A simple command is a sequence of optional variable assignments followed by words and redirections separated by blank and 
terminated by a control operator. T he first word specifies the command to be executed. T he remai ning words are passed as 
arguments to the invoked command. 

The return value of a simple command is its exit status, or 128+n if the command is terminated by signal n. 

PIPELINES 

A pipeline is a sequence of one or more commands separated by the character |. Theformatforapipelineis 

[! ] c o mma n d [ | c o mma n d 2 ... ] 

The standard output of command is connected to the standard input of command 2 . This connection is performed before any 
redirections specified by the command. (See the "Redirection" section, later in this manual page.) 

If the reserved word 1 precedes a pipeline, the exit status of that pipeline is the logical not of the exit status of the last 
command. Otherwise the statusof the pipeline is the exit status of the last command. The shell waits for all commandsin 
the pipeline to terminate before returning a value 

Each command in a pipeline is executed as a separate process (that is, in a subshell). 

LISTS 

A list is a sequence of one or more pipelines separated by one of these operators &&, or 11, and terminated by one of 
these: ;, &, Or<newline>. 

Of these list operators && and 11 have equal precedence, followed by ; and &, which have equal precedence 
If a command isterminated by the control operator &, the shell executes the command in the background in a subshell. The 
shell does not wait for the command to finish, and the return status iso. Commands separated by a; are executed sequen¬ 
tially; the shell waits for each command to terminate in turn. The return status is the exit status of the last command 
executed. 

Thecontrol operators && and 11 denote and lists and or lists respectively. An and list has the form: 


command isexecuted if, and only if, command returnsan exit status of zero. 
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An or list has the form 
command command2 

command isexecuted if, and only if, command returnsa non-zero exit status. T he return status of and and or lists istheexit 
status of the last command executed in the list. 

COMPOUND COMMANDS 

A compound command is one of the following: 

(list) 

list isexecuted in a subshell. Variable assignments and built-in commands that affect the shell's environment do not remain 
in effect after the command completes The return status istheexit status of list. 


i i st is simply executed in the current shell environment. This is known as a group command. The return status is the exit 
status of i i st. 

for name [ in word;] do list ; done 

The list of words following in is expanded, generating a list of items The variable name is set to each element of this list in 
turn, and list isexecuted each time. If the in word is omitted, the for command executes i i st once for each positional 
parameter that is set. (See "Parameters" later in this manual page) 

select n a me [ in wo r d ; ] do I i s t ; done 

The list of words following in is expanded, generating a list of items The set of expanded words is printed on the standard 
error, each preceded by a number. If the in word is omitted, the positional parameters are printed. (See "Parameters.") The 
PS3 prompt is then displayed and a line read from the standard input. If the line consists of the number corresponding to 
oneof the displayed words, then the value of name is set to that word. If the line isempty, the words and prompt are 
displayed again. If eof is read, the command completes Any other value read causes name to be set to null. The line read is 
saved in the variable reply. The list isexecuted after each selection until a break or return command isexecuted. The exit 
status of select is the exit status of the last command executed in list, or zero if no commands were executed. 

A case command first expands no r d, and tries to match it against each pattern in turn, using the same matching rules as for 
pathname expansion. (See "Pathname Expansion," later in this manual page) When a match isfound, the corresponding list 
isexecuted. After thefirst match, no subsequent matches are attempted. The exit status is zero if no patterns are matches 
Otherwise, it is the exit status of the last command executed in i i st. 

if list then list [ elif list then list ] ... [ else list ] fl 

The if list isexecuted. If its exit status is zero, the then list isexecuted. Otherwise, each eiif list isexecuted in turn, and if its 
exit status is zero, the corresponding then list isexecuted and the command completes Otherwise, the else list isexecuted, if 
present. The exit status is the exit status of the last command executed, or zero if no condition tested True. 

while list do I i st done 


The while command continuously executes the do list as long as the last command in i i st returnsan exit status of zero. The 
until command is identical to the while command, except that the test is negated; the do list isexecuted as long as the last 
command in i i st returns a non-zero exit status The exit status of the while and until commands istheexit status of the last 
do list command executed, or zero if none was executed. 

[ function ] name () { list; } 

This defines a function named name. The body of the function isthe list of commands between {and }. This list isexecuted 
whenever name is specified as the name of a simple command. T he exit status of a function is the exit status of the last 
command executed in the body. (See "Functions," later in this manual page) 
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COMMENTS 

In a noninteractive shell, or an interactive shell in which the -o interactive-comments option to the set builtin isenabled, a 
word beginning with # causes that word and all remaining characters on that line to be ignored. An interactive shell without 
the -o interactive-comments option enabled doesnot allow comments. 


QUOTING 

Quoting is used to remove the special meaning of certain characters or words to the shell. Quoting can be used to disable 
special treatment for special characters, to prevent reserved words from being recognized as such, and to prevent parameter 
expansion. 

Each of the metacharacters listed earlier under "Definitions" has special meaning to the shell and must be quoted if it is to 
represent itself. There are three quoting mechanisms; the escape character, single quotes, and double quotes. 

A nonquoted backslash (\) is the escape character. It preservesthe literal value of the next character that follows, with the 
exception of <newiine>.lf a \<newiine> pair appears, and the backslash is not quoted, the \<newiine> istreated as a line 
continuation; that is, it iseffectively ignored. 

Enclosing characters in single quotes preserves the literal value of each character within the quotes A single quote may not 
occur between single quotes even when preceded by a backslash. 

Enclosing characters in double quotes preserves the literal value of all characters within the quotes with the exception of$, \ 
and \. The characters $ and 1 retain their special meaning within double quotes. The backslash retains its special meaning 
only when followed by one of the following characters $, \ 11 , \, or <newiine>. A double quote may be quoted within double 
quotes by preceding it with a backslash. 

The special parameters* and @ have special meaning when in double quotes. (See "Parameters," next.) 

PARAMETERS 

A parameter isan entity that stores values, somewhat like a variable in a conventional programming language. It can be a 
name a number, or one of the special characters listed under "Special Parameters" following. For the shell's purposes, a 
variable is a parameter denoted by a name 

A parameter isset if it has been assigned a value. The null string is a valid value Once a variable isset, it may be unset only 
by using the unset built-in command. (See "Shell Built-in Commands," later in this manual page.) 

A variable may be assigned to by a statement of the form: 

n a me = [ v a I lie] 

If vai ue is not given, the variable is assigned the null string. All values undergo tilde expansion, parameter and variable 
expansion, command substitution, arithmetic expansion, and quote removal. If the variable has its-i attribute set (see 
declare in "Shell Built-in Commands") then value issubject to arithmetic expansion even if the $[...] syntax does not 
appear. W ord splitting is not performed, with the exception of "$r, as explained under "Special Parameters" Pathname 
expansion is not performed. 

POSITIONAL PARAMETERS 

A positional parameter is a parameter denoted by one or more digits other than the single digit 0. Positional parameters are 
assigned from the shell's arguments when it isinvoked, and may be reassigned using theset built-in command. Positional 
parameters may not be assigned to with assignment statements. The positional parameters are temporarily replaced when a 
shell function is executed. (See"Functions," later in thismanual page.) 

When a positional parameter consisting of more than a single digit isexpanded, it must be enclosed in braces. (See 
"Expansion," later in thismanual page) 

SPECIAL PARAMETERS 

Theshell treats several parameters specially. T hese parameters may only be referenced; assignment to them is not allowed. 
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* Expandsto the positional parameters, starting from one. When the expansion occurswithin double 
quotes, it expands to a single word with the value of each parameter separated by the first character 
oftheiFS special variable. That is, ■$*■ is equivalent to "$ic$2c... M , where cisthefirst character of 
the value of the ifs variable If ifs is null or unset, the parameters are separated by spaces. 

@ Expandsto the positional parameters, starting from one. When the expansion occurswithin double 

quotes, each parameter expands as a separate word. That is, "$@" is equivalent to "$i""$2" .... 

W hen there are no positional parameters, "$@" and $@ expand to nothing (in other words, they are 
removed). 

# Expandsto the number of positional parameters in decimal. 

? Expandstothestatusofthemostrecentlyexecutedforeground pipeline. 

Expandsto the current option flags as specified upon invocation, by the set built-in command, or 
those set by the shell itself (such asthe-t flag). 

$ Expandsto the process ID of the shell. In a o subshell, it expands to the process ID of the current 

shell, not the subshell. 

i Expandsto the process ID of the most recently executed background (asynchronous) command. 

0 Expandsto the name of the shell or shell script. This isset at shell initialization. If bash is invoked 

with a file of commands, isset to the name of that file. If bash isstarted with the-c option, then is 
set to thefirst argument after the string to be executed, if one is present. Otherwise, it isset to the 
pathname used to invoke bash, as given by argument zero. 

Expandsto the last argument to the previous command, after expansion. Also set to the full 
pathname of each command executed and placed in the environment exported to that command. 


SHELL VARIABLES 

T hefollowing variables are set by the shell: 


PPID 

PWD 

OLDPWD 

REPLY 

UID 

EUID 

BASH 

BASH_VERSION 

SHLVL 

RANDOM 


SECONDS 


LINENO 


The process ID of the shell's parent. 

The current working directory asset by the cd command. 

The pra/ious worki ng di rectory as set by the cd command. 

Set to the line of input read by the read built-in command when no arguments are 
supplied. 

Expandsto the user ID of the current user, initialized at shell startup. 

Expandsto the effective user ID of the current user, initialized at shell startup. 
Expandsto the full pathname used to invoke this instance of bash. 

Expandsto the version number of this instance of bash. 

Incremented by one each time an instance of bash isstarted. 

Each time this parameter is referenced, a random integer is generated. The sequence 
of random numbers may be initialized by assigning a value to random. If random is 
unset, it loses its special properties, a/en if it is subsequently reset. 

Each time this parameter isreferenced, thenumber of seconds since shell invocation 
is returned. If a value is assigned to seconds, the value returned upon subsequent 
references is the number of seconds si nee the assignment plusthe value assigned. If 
seconds is unset, it loses its special properties, even if it is subsequently reset. 

Each time thisparamdter isreferenced, the shell substitutes a decimal number 
representing the current sequential line number (starting with 1) within a script or 
function. When notin a script or function, the value substituted is not guaranteed to 
be meaningful. When in a function, the value is not the number of the source line 
that the command appears on (that information has been lost by the time the 
function isexecuted), butisan approximation of thenumber of simple commands 
executed in the current function. If lineno is unset, it loses its special properties, even 
if it is subsequently reset. 
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The history number, or index in the history list, of the current command. If histcmd 
is unset, it loses its special properties, even if it is subsequently reset. 

The value of the last option argument processed bythegetopts built-in command. 
(See"Shell Built-in Commands," later in thismanual page). 

The index of the next argument to be processed bythegetopts built-in command. 
(See"Shell Built-in Commands.") 

Automatically sdt to a string that uniquely describes the type of machine on which 
bash is executing. The default is system-dependent. 

Automatically set to a string that describes the operating system on which bash is 
executing. The default is system-dependent. 


wing variables are used by the shell, 
/ing list: 


ih assigns a default value to a variable; these cases are noted ir 


The search path for commands It is a colon-separated list of directories in which the 
shell looks for commands (See "Command Execution," later in thismanual page). 
The default path is system-dependent, and issetbytheadministratorwho installs 
bash. A common value is /usr/gnu/bin: /usr/local/bin:/usr/ucb: /bin: /usr/bin:. 

T he home directory of the current user; the default argument for the cd built-in 
command. 

The search path for the cd command. This is a colon-separated list of directories in 
which the shell looks for destination directories specified by thecd command. A 
sample value is. :':/usr. 

If this parameter is set when bash isexecuting a shell script, its value is interpreted as 
a filename containing commands to initializethe shell, asin .bashrc. Thevalueof 
env is subjected to parameter expansion, command substitution, and arithmetic 
expansion before being interpreted as a pathname, path is not used to search for the 
resultant pathname. 

If this parameter is set to a filename and the mailpath variable is not sdt, bash informs 
the user of the arrival of mail in the specified file. 

Specifies how often (in seconds) bash checksfor mail. The default is60 seconds 
When it is time to check for mail, the shell does so before prompting. If this variable 
is unset, the shell disables mail checking. 

A colon-separated list of pathnames to be checked for mail. The message to be 
printed may be specified by separating the pathname from the message with a 
question mark (?). $_ stands for the name of the current mailfile. 

Example: 


bash supplies a default value for this variable but the location of the user mail files 
that it uses is system-dependent (for example, /usr/spooi/maii/$usER). 

If set, and afile that bash is checking for mail has been accessed since the last time it 
was checked, the message "The mail in mail-file has been read" is printed. 

The value of this parameter is expanded (see "Prompting," later in thismanual page) 
and used as the primary prompt string. The default value isbash\$. 

The value of this parameter is expanded and used as the secondary prompt string. 

T he default is >. 
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PS 3 


PS 4 


HISTSIZE 

HISTFILE 


HISTFILESIZE 


OPTERR 


PROMPT_COMMAND 

IGNOREEOF 


TMOUT 


FCEDIT 

FIGNORE 


INPUTRC 


The value of this parameter is used as the prompt for the select command. (See 
"Shell Grammar," earlier in this manual page.) 

The value of this parameter is expanded and the value is printed before each 
command bash displays during an execution trace Thefirst character of ps4 is 
replicated multi pie times, as necessary, to indicate multiple levels of indirection. The 
default is+. 

The number of commands to remember in the command history, (See"H istory," 
later in this manual page.) The default value is 500. 

The name of thefilein which command history is saved. (See"H istory.") The 
default value is '/.bash_history. If unset, the command history is not saved when an 
interactive shell exits. 

The maximum number of lines contained in the history file When this variable is 
assigned a value, the history file is truncated, if necessary, to contain no more than 
that number of lines T he default value is 500. 

If set to the value 1 , bash displays error messages generated by thegetopts built-in 
command. (See "Shell Built-in Commands."), opterr isinitialized to 1 each time the 
shell isinvoked or a shell script isexecuted. 

If set, the value is executed as a command prior to issuing each primary prompt. 
Controls the action of the shell on receipt of an eof character as the sole input. If set, 
the value is the number of consecutive eof characters typed as the first characters on 
an input line before bash exits If the variable exists but does not haveanumeric 
value, or hasno value, the default value is 10. If it does not exist, eof signifies the end 
of input to theshell. Thisisonly in effect for interactive shells. 

If set to a value greater than zero, the value is interpreted as the number of seconds 
to wait for input after issuing the primary prompt, bash terminates after waiting for 
that number of seconds if input does not arrive. 

The default editor for the fc built-in command. 

A colon-separated list of suffixes to ignore when performing filename completion. 
(See "Readline" later in this manual page) A filename whose suffix matches one of 
theentriesin fignore isexcluded from the list of matched filenames A sample value 
is. 0:’. 

T he filename for the readiine startup file, overriding the default of '/.inputrc. (See 
"Readline") 


history_control HISTCONTROL 


command_oriented_history 

glob_dot_filenames 

allow-null_glob_expansion 

histchars 


If set, bash reports terminated background jobsimmediately, rather than waiting 
until before printing the next primary prompt. (See also the -b option to the set 
built-in command.) 

If set to a value of ignorespace, lines that begin with a space character are not entered 
on the history list. If set to a value of ignoredups, lines matching the last history line 
are not entered. A value of ignoneboth combines the two options If unset, or if set to 
any other value than the preceding, all lines read by the parser are saved on the 
history list. 

If set, bash attempts to save all lines of a multiple-line command in the same history 
entry. T his allows easy reediting of multiline commands 
If set, bash includes filenames beginning with aperiod (.) in the results of pathname 
expansion. 

If set, bash allows pathname patterns which match no files (see "Pathname 
Expansion") to expand to a null string, rather than themselves 
The two or three characters that control history expansion and tokenization. (See 
"H istory Expansion," later in this manual page) Thefirst character is the history 
expansion character; that is the character that signals the start of a history expansion, 
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hostname_completion_file HOSTFILE 


noclobber 






normally i. The second character is the quick substitution character, which is used as 
shorthand for rerunning the previous command entered, substituting one string for 
another in the command. The default is*. The optional third character is the 
character that signifies that the remainder of the line is a comment, when found as 
the first character of a word, normally #. The history comment character causes 
history substitution to be skipped for the remaining words on the line. It does not 
necessarily cause the shell parser to treat the rest of the line as a comment. 

If set, the shell does not follow symbolic links when executing commands that 
change the current working directory. 11 uses the physical directory structure instead. 
By default, bash follows the logical chain of directories when performing commands 
that change the current directory, such as cd. See also the description of the-p 
option to the set builtin ("Shell Built-in Commands"). 

Containsthe name of a file in the same format as /etc/hosts that should be read 
when theshell needs to complete a hostname T hefile may be changed interactively; 
the next time hostname completion isattempted bash adds the contents of the new 
file to the already existing database 

If set, bash does not overwrite an existing file with the>, >&, and <> redirection 
operators This variable may be overridden when creating output files by using the 
redirection operator >| instead of >. (See also the-c option to the set built-in 
command.) 

This variable controls how theshell interacts with the user and job control. If this 
variable is set, single word simple commands without redirections are treated as 
candidates for resumption of an existing stopped job. There is no ambiguity allowed; 
if there is more than one job beginning with the string typed, the job most recently 
accessed is selected. The name of a stopped job, in this context, is the command line 
used to start it. If set to the value exact, thestring supplied must match the name of 
a stopped job exactly; if set to substring, thestring supplied needs to match a 
substring of the nameof a stopped job. The substring value provides functionality 
analogous to the%? job ID. (See "Job Control," later in this manual page) If set to 
any other value, the supplied string must be a prefix of a stopped job's name this 
provides functionality analogous to the % job id. 

If this variable exists, a noninteractive shell will not exit if it cannot execute the file 
specified in the exec built-in command. An interactive shell does not exit if exec 
fails 

If this is set, an argument to thecd built-in command that is not a directory is 
assumed to be the name of a variable whose value is the directory to change to. 


EXPANSION 

Expansion isperformed on thecommand line after it has been split into words. There are seven kinds of expansion 
performed: brace expansion, tilde expansion, parameter and variable expansion, command substitution, arithmetic expan¬ 
sion, word splitting, and pathname expansion. 

The order of expansions is as follows brace expansion, tilde expansion, parameter, variable command, and arithmetic 
substitution (done in a left-to-right fashion), word splitting, and pathnameexpansion. 

On systems that can support it, there is an additional expansion available: process substitution. 

Only brace expansion, word splitting, and pathnameexpansion can change the number of words of theexpansion; other 
expansions expand a single word to a single word. The single exception to this isthe expansion of as explained earlier. 
(See "Parameters") 



BRACE EXPANSION 

Brace expansion isa mechanism by which arbitrary strings may be generated. This mechanism issimilar to pathname 
expansion, but the filenames generated need not exist. Patterns to be brace expanded take the form of an optional preamble, 
followed by a series of comma-separated strings between a pair of braces, followed by an optional postamble. T he preamble is 
prepended to each string contained within the braces and the postamble is then appended to each resulting string, 
expanding left to right. 

Braceexpansionsmay be nested. The results of each expanded string are not sorted; left to right order is preserved. For 
example, a{d,c,b}e expands into ade ace abe. 

Brace expansion is performed before any other expansions and any characters special to other expansions are preserved in the 
result. It is strictly textual, bash does not apply any syntactic interpretation to the context of the expansion or the text 
between the braces 

A correctly formed brace expansion must contain unquoted opening and closing braces and at least one unquoted comma. 
Any incorrectly formed brace expansion is left unchanged. 

This construct istypically used as shorthand when the common prefix of the strings to be generated is longer than in the 
preceding example such as 

mkdir /usr/local/src/bash/{old,new,dist,bugs} 


or 

chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} 

Brace expansion introduces a slight incompatibility with traditional versions of sh, the Bourne shell, sh does not treat 
opening or closing braces specially when they appear as part of a word, and preserves them in the output, bash removes 
braces from words as a consequence of brace expansion. For example, a word entered to sh asfiie-ci ,2> appears identically in 
the output. The same word is output as ftiei fiie2 after expansion by bash. If strict compatibility with sh is desired, start 
bash with the-nobraceexpansion flag (see "0 ptions," earlier in this manual page) or disable brace expansion with the+o 
braceexpand option to the set command. (See "Shell Built-in Commands.") 

TILDE EXPANSION 

If a word begins with a tilde character ( ), all of the characters preceding the first slash (or all characters, if there is no slash) 
are treated as a possible login name. If this login name is the null string, the tilde is replaced with the value of the parameter 
home. If home is unset, the home directory of the user executing the shell is substituted instead. 

If a + follows the tilde the valueofpwD replacesthe tilde and + If a- follows, the value of oldpwd is substituted. Ifthe value 
following the tilde isa valid login name, the tilde and login name are replaced with the home directory associated with that 
name If the name is invalid, or the tilde expansion fails, the word is unchanged. 

Each variable assignment is checked for unquoted instancesof tildesfollowing a : or =. In these cases, tilde substitution is 
also performed. Consequently, one may use pathnames with tildes in assignments to path, mailpath, and cdpath, and the shell 
assigns the expanded value. 

PARAMETER EXPANSION 

T he $ character introduces parameter expansion, command substitution, or arithmetic expansion. The parameter name or 
symbol to be expanded may be enclosed in braces, which are optional but serve to protect the variable to be expanded from 
characters immediately following it which could be interpreted as part of the name. 

${parameter } Thevalueof parameter is substituted. The braces are required when parameter isa positional parameter 

with more than onedigit, or when parameter isfollowed by a character that is not to be interpreted as part 
of its name 

In each of the following cases, word is subject to tilde expansion, parameter expansion, command substitution, and arithmetic 
expansion, bash tests for a parameter that is unset or null; omitting the colon results in a test only for a parameter that is 
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${p a r a met e r :-word} 
${parameter :=word} 

${parameter :?word} 

${p a r a met e r : +wo r d} 

${#p a r a me t e r} 

${parameter #wor d} 
${parameter##wo r d} 

${p a r a met e r %wo r d > 
${p a r a met er %%wor d} 


Use default values If parameter is unset or null, the expansion of word issubstituted. Otherwise the 
valueof parameter is substituted. 

Assign default values. If parameter is unset or null, the expansion of word is assigned to parameter. 
The value of parameter isthen substituted. Positional parameters and special parameters may not be 
assigned to in this way. 

D isplay Error if null or unset. If pa r a met e r is null or unset, the expansion of wo r d (or a message to 
that effect if wor d is not present) is written to the standard error and the shell, if it is not interactive, 
exits Otherwise, the value of parameter issubstituted. 

Use Alternate Value. If parameter is null or unset, nothing issubstituted; otherwise, the expansion 
of word issubstituted. 

The length in characters of the value of par a meter issubstituted. If parameter is* or e, the length 
substituted isthe length of * expanded within double quotes 

The word isexpanded to produce a pattern just as in pathname expansion. If the pattern matches 
the beginning of the value of p a r a me t e r , then the expansion is the value of par a met er with the 
shortest matching pattern deleted (the # case) or the longest matching pattern deleted (the ## case). 
The word isexpanded to produce a pattern just as in pathname expansion. If the pattern matches a 
trailing portion of the value of parameter , then the expansion is the value of parameter with the 
shortest matching pattern deleted (the % case) or the longest matching pattern deleted (the %% case). 


COMMAND SUBSTITUTION 

Command substitution allows the output of a command to replace the command name 
There are two forms 


or 


performstheexpansion by executing command and replacing the command substitution with the standard output of the 
command, with any trailing newlines deleted. 

When the old-style backquote form of substitution is used, backslash retains its literal meaning except when followed by $, \ 
or \. When using the $(command ) form, all characters between the parentheses make up the command; none are treated 
specially. 

Command substitutions may be nested. To nest when using the old form, escape the inner backquoteswith backslashes. 

If the substitution appears within double quotes, word splitting and pathname expansion are not performed on the results. 

ARITHMETIC EXPANSION 

Arithmetic expansion allows the evaluation of an arithmetic expression and the substitution of the result. T here are two 
formats for arithmetic expansion: 

$[expression] 

$((expression)) 

The expression is treated as if it were within double quotes, but a double quote inside the braces or parentheses is not treated 
specially. All tokensin theexpression undergo parameter expansion, command substitution, and quote removal. Arithmetic 
substitutions may be nested. 

The evaluation is performed according to the rules listed under "Arithmetic Evaluation," later in thissection. If expr es s i on is 
invalid, bash prints a message indicating failure and no substitution occurs. 

PROCESS SUBSTITUTION 

Processsubstitution issupported on systems that support named pipes (FIFOs) orthe/dev/fd method of naming open files. 
Ittakestheform of <(i i st ) or >(i i st ). T he process list is run with its input or output connected to a FIFO orsomefilein / 





dev/fd. T he name of thisfile ispassed as an argument to the current command asthe result of theexpansion. If the >(i i st) 
form is used, writing to the file will provide input for list. If the<(i i st) form is used, the file passed as an argument should 
be read to obtain the output of list. 

On systems that support it, process substitution is performed simultaneously with parameter and variable expansion, 
command substitution, and arithmetic expansion. 

WORD SPLITTING 

The shell scans the results of parameter expansion, command substitution, and arithmetic expansion that did not occur 
within double quotes for word splitting. 

Theshell treats each character of iFsasa delimiter, and splits the results of the other expansions into wordson these 
characters. If the value of ifs isexactly <space><tat»<newiine>, the default, then any sequence of ifs characters serves to 
delimit words. If ifs has a value other than the default, then sequences of the whitespace characters space and tab are ignored 
at the beginning and end of the word, as long asthe whitespace character is in the value of ifs (an ifs whitespace character). 
Any character in ifs that is not ifs whitespace, along with any adjacent ifs whitespace characters, delimits a field. A 
sequence of ifs whitespace characters is also treated asa delimiter. If the value of ifs is null, no word splitting occurs ifs 
cannot be unset. 

Explicit null arguments ("■ or ") are retained. Implicit null arguments resulting from theexpansion of parameters that have 
no values are removed. 

N otethat if no expansion occurs no splitting is performed. 

PATHNAME EXPANSION 

Afterword splitting, unless the -f option has been set, bash scans each word for the characters*, ?, and [. If one of these 
characters appears then the word is regarded as a pattern and replaced with an alphabetically sorted list of pathnames 
matching the pattern. If no matching pathnames are found, and theshell variable aiiow_nuii_giob_expansion is unset, the 
word is left unchanged. If the variable is set, and no matches are found, the word is removed. When a pattern is used for 
pathname generation, the character (.) at the start of a name or immediately following a slash must be matched explicitly, 
unless the shell variablegiob_dot_fiienames is set. The slash character must always be matched explicitly. In other cases, the 
(.) character is not treated specially. 

The special pattern characters have thefollowing meanings: 

* M atches any string, including the null string. 

? M atches any single character. 

[...] M atches any one of the enclosed characters A pair of characters separated by a minus sign denotes a range; 

any character lexically between those two characters, inclusive is matched. If the first character following 
the [ isa i or a -, then any character not enclosed is matched. A - or ] may be matched by including it as 
the first or last character in the set. 

QUOTE REMOVAL 

After the preceding expansions all unquoted occurrences of the characters\, ',and ■ areremoved. 

REDIRECTION 

Before a command is executed, its input and output may be redirected using a special notation interpreted by the shell. 
Redirection may also be used to open and close files for the current shell execution environment. Thefollowing redirection 
operators may precede or appear anywhere within a simple command or may follow a command. Redirectionsare processed 
in the order they appear, from left to right. 

In thefollowing descriptions if the file descriptor number is omitted, and the fi rst character of the redirection operator is<, 
the redirection refers to the standard input (file descriptor 0). If the first character of the redirection operator is >, the 
redirection refers to the standard output (file descriptor 1 ). 
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The word that follows the redirection operator in thefollowing descriptionsissubjected to brace expansion, tilde expansion, 
parameter expansion, command substitution, arithmetic expansion, quote removal, and pathname expansion. If it expands to 
more than one word, bash reports an error. 

N otethat the order of redirections is significant. For example the command: 

Is > di rIist 2>&1 

directs both standard output and standard error to the file di r i i st , while the command 

Is 2>&1 > di rIist 

directs only the standard output to file di r i i st , because the standard error was duplicated as standard output before the 
standard output was redirected to dirlist. 

REDIRECTING INPUT 

Redirection of input causes the file whose name results from the expansion of word to be opened for reading on file 
descriptor n, or the standard input (file descriptor 0) if n is not specified. 

Thegeneral format for redirecting input is 

[n]<word 

REDIRECTING OUTPUT 

Redirection of output causes the file whose name results from the expansion of word to be opened for writing on file 
descriptor n, or the standard output (file descriptor 1) if n is not specified. If the file does not exist, it is created; if it does 
exist it is truncated to zero size. 

Thegeneral format for redirecting output is 

[ n]>w 0 r d 

If the redirection operator is > |, then the value of the -c option to the set built-in command is not tested, and file creation is 
attempted. (See also the description of nociobber under "Shell Variables," earlier in thismanual page) 

APPENDING REDIRECTED OUTPUT 

Redirection of output in thisfashion causes the file whose name results from the expansion of word to be opened for 
appending on file descriptor n, or the standard output (file descriptor 1) if n is not specified. If the file does not exist, it is 
created. 

Thegeneral format for appending output is 


REDIRECTING STANDARD OUTPUTAND STANDARD ERROR 

bash allows both the standard output (file descriptor 1) and the standard error output (file descriptor 2) to be redirected to 
thefile whose nameistheexpansion of word with thisconstruct. 

There are two formats for redirecting standard output and standard error: 


and 


Of the two forms, the first is preferred. This is semantically equivalent to 

>word 2>&1 

HERE-DOCUMENTS 

This type of redirection instructs the shell to read input from the current source until a line containing only word (with no 
trailing blanks) is seen. All of the lines read up to that point are then used as the standard input for a command. 



Theformat of here-documentsisas follows 


N o parameter expansion, command substitution, pathname expansion, or arithmetic expansion is performed on word. If any 
characters in word are quoted, the del i mi ter isthe result of quote removal on word, and the lines in the here-document are not 
expanded. Otherwise, all lines of theher e-document are subjected to parameter expansion, command substitution, and 
arithmetic expansion. In the latter case, the pair \<newiine> is ignored, and \ must be used to quote the characters\, $, and '. 
If the redirection operator is «-, then all leading tab characters are stripped from input lines and the line containing 
delimiter. This allows here-documents within shell scripts to beindented in anatural fashion. 

DUPLICATING FILE DESCRIPTORS 

The redirection operator: 

[n]<&wo r d 

is used to duplicate input file descriptors. If no r d expands to one or more digits, the file descriptor denoted by n is made to be 
a copy of that file descriptor. If word evaluates to -, file descriptor n isdosed. If n is not specified, the standard input (file 
descriptor®) is used. 

The operator: 

[n]>&wor d 


is used similarly to duplicate output file descriptors If n is not specified, the standard output (file descriptor i) is used. Asa 
special case if n is omitted, and word does not expand to one or more digits, the standard output and standard error are 
redirected as described previously. 

OPENING FILE DESCRIPTORS FOR READING AND WRITING 

The redirection operator: 


causes the file whose name is the expansion of word to be opened for both reading and writing on file descriptor n, orasthe 
standard input and standard output if n is not specified. If the file does not exist, itiscreated. 

FUNCTIONS 

A shell function, defined asdescribed above under "Shell Grammar," stores a series of commands for later execution. 
Functions are executed in the context of the current shell; no new process is created to interpret them (contrast this with the 
execution of a shell script). When a function is executed, the arguments to the function become the positional parameters 
during its execution. The special parameter# is updated to reflect the change. Positional parameter 0 is unchanged. 

Variables local to the function may be declared with theiocai built-in command. Ordinarily, variables and their values are 
shared between the function and its caller. 

If the built-in command return isexecuted in afunction, thefunction completes and execution resumes with the next 
command after the function call. When afunction completes, the values of the positional parameters and the special 
parameter # are restored to the values they had prior to function execution. 

Function names may be listed with the -f option to the declare or typeset built-in commands. Functions may be exported 
so that subshells automatically have them defined with the -f option to the export builtin. 

Functions may be recursive N 0 limit is imposed on the number of recursive calls 

ALIASES 

The shell maintainsa list of aliases that may be set and unsdtwith the alias and unaiias built-in commands (See "Shell 
Built-in Commands"). Thefirst word of each command, if unquoted, ischecked to see if it has an alias If so, that word is 
replaced by the text of the alias The alias name and the replacement text may contain any valid shell input, including the 
metacharacters listed above, with the exception that the alias name may not contain =. Thefirst word of the replacement text 
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is tested for aliases but a word that is identical to an alias being expanded is not expanded a second time. This means that 
one may alias is to is -F,for instance, and bash does not try to recursively expand the replacement text. If the last character 
of the alias value is a blank, then the next command word following the alias is also checked for alias expansion. 

Aliases are created and listed with the alias command, and removed with theunaiias command. 

There is no mechanism for using arguments in the replacement text, as in csh. If arguments are needed, a shell function 
should be used. 

Aliases are not expanded when the shell is not interactive. 

The rules concerning the definition and use of aliases are somewhat confusing, bash always reads at least one complete line of 
input before executing any of the commands on that line. Aliases are expanded when a command is read, not when it is 
executed. Therefore, an alias definition appearing on the same line as another command does not take effect until the next 
lineof inputisread. Thismeansthatthecommandsfollowing the alias definition on that lineare not affected by the new 
alias This behavior isalso an issue when functions are executed. Aliases are expanded when the function definition isread, 
not when thefunction isexecuted, because a function definition is itself a compound command. As a consequence, aliases 
defined in a function are not available until after that function isexecuted. To be safe always put alias definitionson a 
separate line, and do not use alias in compound commands. 

Note that for almost every purpose aliases are superseded by shell functions 

JOB CONTROL 

J ob control refers to the ability to selectively stop (suspend) the execution of processes and continue (resume) their execution 
at a later point. A user typically employs thisfacility via an interactive interface supplied jointly by the system's terminal 
driver and bash. 

Theshell associates a job with each pipeline It keeps a table of currently executing jobs, which may be listed with the jobs 
command. When bash starts a job asynchronously (in the background), it prints a line that looks like this: 

[1] 25647 

indicating that this job is job number 1 and that the process ID of the last process in the pipeline associated with this job is 
25647. All of the processes in a single pipeline are members of the samejob. bash usesthejob abstraction as the basisfor job 
control. 

T o facilitate the implementation of the user interface to job control, the system maintains the notion of a current terminal 
process group ID. M embers of this process group (processes whose process group ID is equal to the current terminal process 
group ID) receive keyboard-generated signals such assiGiNT. These processes are said to be in the foreground. Background 
processes are those whose process group ID differs from the terminal's; such processes are immune to keyboard-generated 
9 gnals. Only foreground processes are allowed to read from or write to the terminal. Background processes that attempt to 
read from (write to) the terminal are sent a sigttin (sigttou) signal by theterminal driver, which, unless caught, suspends 
the process 

If the operating system on which bash is running supports job control, bash allows you to use it. T yping the suspend 
character (typically "z, controi-z) while a process is running causes that process to be stopped and returns you to bash. 
Typing the delayed suspend character (typically ~y, controi-y) causes the process to be stopped when it attempts to read 
input from theterminal, and control to be returned to bash. You may then manipulate the state of this job, using the bg 
command to continue it in the background, thefg command to continue it in the foreground, or the kin command to kill 
it. A Ctrl+Z takes effect immediately, and has the additional side effect of causing pending output and typeahead to be 
discarded. 

There are a number of ways to refer to a job in the shell. T he character % introduces a job name Job number n may be 
referred to as %n. A job may also be referred to using a prefix of the name used to start it, or using a substri ng that appears i n 
its command line. For example %ce refers to a stopped cejob. If a prefix matches more than onejob, bash reports an error. 
Using%?ce, on theother hand, refers to any job containing thestringce in its command line. If the substring matches more 
than onejob, bash reports an error. The symbols %% and %+ refer to the shell's notion of the current job, which isthe last job 



stopped while it was in the foreground. T he previous job may be referenced usi ng %-.l n output pertaining to jobs (for 
example, the output of the jobs command), the current job is always flagged with a+, and the previous job with a-. 

Simply naming a job can be used to bring it into the foreground: %i isa synonym for fg %i, bringing job 1 from the 
background into the foreground. Similarly, %i & resumes job 1 in the background, equivalent to bg %i. 

Theshell learns immediately whenever a job changes state Normally, bash waits until itisaboutto print a prompt before 
reporting changes in a job's status so as to not interrupt any other output. If the-b option to the set built-in command isset, 
bash reports such changes immediately. (See also the description of the notify variablein "Shell Variables," earlier in this 
manual page) 

If you attempt to exit bash while jobs are stopped, theshell prints a message warning you. You may then use the jobs 
command to inspect their status. If you do this, or try to exit again immediately, you are not warned again, and thestopped 
jobs are terminated. 

SIGNALS 

When bash is interactive it ignores sigterm (so that kin 0 does not kill an interactive shell), and sigint is caught and 
handled (so thatthewait built-in is interruptible). In all cases, bash ignores sigquit. If job control isin effect, bash ignores 

SIGTTIN, SIGTTOU, and SIGTSTP. 

Synchronous jobs started by bash have signals set to the values inherited by the shell from its parent. W hen job control isnot 
in effect, background jobs (jobsstarted with &) ignore sigint and sigquit. Commands run as a result of command substitu¬ 
tion ignore the keyboard-generated job control signals sigttin, sigttou, and sigtstp. 

COMMAND EXECUTION 

After a command has been split into words, if it results in a simple command and an optional list of arguments, the 
following actionsare taken. 

If the command name contains no slashes, theshell attempts to locate it. If there existsa shell function by that name, that 
function is invoked as described earlier in "Functions." If the name does not match a function, theshell searches for it in the 
list of shell builtins. If a match isfound, that builtin is invoked. 

If the name is neither a shell function nor a builtin, and contains no slashes, bash searches each element of the path for a 
directory containing an executablefile by that name. If the search is unsuccessful, theshell prints an error message and 
returns a nonzero exit status. 

If the search is successful, or if the command name contains one or more slashes, theshell executes the named program. 
Argument 0 isset to the name given, and the remaining arguments to the command are set to the arguments given, if any. 

If this execution fails because the file is not in executable format, and the file is not a directory, it is assumed to be a shell 
script, a file containing shell commands A subshell is spawned to execute it. Thissubshdl reinitializes itself, so that the effect 
is as if anew shell had been invoked to handle the script, with the exception that the locations of commands remembered by 
the parent (see hash under "Shell Built-in Commands") are retained by the child. 

If the program is a file beginning with #!, the remainder of the first line specifies an interpreter for the program. Theshell 
executes the specified interpreter on operating systems that do not handle this executable format themselves. The arguments 
to the interpreter consist of a single optional argument following the interpreter name on thefirst line of the program, 
followed by the name of the program, followed by the command arguments, if any. 

ENVIRONMENT 

When a program is invoked, it is given an array of strings called the environment. Thisisa list of name/value pairs, of the 
form name=value. 

Theshell allows you to manipulate the environment in several ways. On invocation, the shell scans its own environment and 
creates a parameter for each name found, automatically marking it for export to child processes. Executed commands inherit 
the environment. The export and declare -x commands allow parameters and functionsto be added to and deleted from the 
environment. If the value of a parameter in the environment is modified, the new value becomes part of the environment, 
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replacing theold. The environment inherited by any executed command consistsof theshell's initial environment, whose 
values may be modified in the shell, less any pairs removed by the unset command, plus any additions via the export and 
declare -x commands. 

The environment for any simple command or function may be augmented temporarily by prefixing it with parameter 
assignments, as described earlier in "Parameters" These assignment statements affect only the environment seen by that 
command. 

If the-k flag issdt (seethe set built-in command), then all parameter assignments are placed in the environment for a 
command, not just those that precede the command name. 

When bash invokes an external command, the variable is set to the full path name of the command and passed to that 
command in its environment. 

EXIT STATUS 

For the purposes of the shell, a command which exits with a zero exit status has succeeded. An exit status of zero indicates 
success. A non-zero exit status indicates failure. When a command terminates on a fatal signal, bash uses the value of 
128+signai as the exit status 

If a command is not found, the child process created to execute it returns a status of 127. If a command is found but is not 
executable, the return status is 126. 

bash itself returns the exit status of the last command executed, unless a syntax error occurs in which case it exits with a non¬ 
zero value. (See also the exit built-in command.) 

PROMPTING 

When executing interactively, bash displays the primary prompt psi when it is ready to read a command, and the secondary 
prompt ps2 when it needs more input to complete a command, bash allows these prompt strings to be customized by 
inserting a number of backslash-escaped special characters that are decoded as follows: 

\t Thecurrenttimein hh: mm: ss format 

\d The date in "W eekday M onth D ate" format (for example, "TueMay26") 

\n Newline 

\s The name of the shell, thebasenameof $0 (the portion following thefinal slash) 

\w The current working directory 

\w The basenameof the current working directory 

\u The username of the current user 

\h The hostname 

\# The command number of this command 

\ i The history number of this command 

\$ If the effecti ve UID iso, a#, otherwise a $ 

\nnn The character corresponding to the octal number nnn 

\\ A backslash 

\[ Begin a sequence of nonprinting characters, which could be used to embed a terminal control sequence 

into the prompt 

\ ] End a sequence of nonprinting characters 

T he command number and the history number are usually different: the history number of a command is its position in the 
history list, which may include commands restored from the history file (see"H istory," later in this manual page), while the 
command number is the position in the sequence of commands executed during the current shell session. After the string is 
decoded, it isexpanded via parameter expansion, command substitution, arithmetic expansion, and word splitting. 
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READLINE 

This is the library that handles reading input when using an interactive shell, unless the-noiineediting option isgiven. By 
default, the line editing commands are similar to those of emacs. A vi-style line editing interface is also avai lable 
In this section, the emacs-style notation is used to denote keystrokes Control keys are denoted bye-key; for example, c-n 
means Ctrl-N. Similarly, mdta keys are denoted by M-key, so m-x meansMeta-x. (On keyboards without a meta key, m-x 
means Esc-X; that is press the Escape key, then theX key. This makes ESC the mdta prefix. The combination m-c-x means 
Esc-Control-x, or press the Escapekey then hold theControl key while pressing the X key.) 

The default key-bindings may be changed with a / .inputnc file The value of the shell variable inputrc, if set, is used instead 
of •/.inputre. Other programsthat use this library may add their own commands and bindings 
For example, placing 

M-Control-u: universal-argument 

or 

into the/.inputrc would make m-c-u execute the readiine command universal-argument.T he following symbolic character 
names are recognized: rubout, del, esc, lfd, newline, ret, return, spc, space, and tab. In addition to command names 
readiine allows keys to be bound to a string that is inserted when the key is pressed (a macro). 

Readline is customized by putting commands in an initialization file The name of thisfile is taken from the value of the 
inputrc variable. If that variable is unset, the default is'/.inputrc. When a program that uses the readiine library starts up, 
theinit file is read, and the key bindings and variables are set. There are only a few basic constructs allowed in the readiine 
init file Blank lines are ignored. Lines beginning with a# are comments Lines beginning with a $ indicate conditional 
constructs. 0 ther lines denote key bindings and variable settings. 

The syntax for controlling key bindingsin the '/.inputrc file issimple. All that is required isthe name of the command or 

the text of a macro and a key sequence to which it should be bound. The name may be specified in oneof two ways: as a 

symbolic key name, possibly with M eta- or Control- prefixes, or as a key sequence When using theform keyname: fund i on- 

na me or macro, keyname isthe name of a key spelled out in English. For example 

Control-u: universal -argument 

Meta-Rubout: backward-kill-word 

Control-o: ">&output" 

In the preceding example, c-u is bound tothefunction universal-argument, m-del is bound tothefunction backward-km- 
word.and c-o isbound to run the macro expressed on therighthand side (that is, to insert the text >&output into the line). 

In thesecond form, -keyseg":functi on-name or mac r o, keys eq differs from keyname in that strings denoting an entire key 
sequence may be specified by placing the sequence within double quotes Some GNU emacs-style key escapes can be used, as 
in the following example: 

"\C-u": universal-argument 
"\C-x\C-r": re-read-init-file 
"\e[11'": "Function Key 1" 

In thisexample, C-u isagain bound to the function universal-argument. C-x C-r isbound to thefunction re-read-init-file, 

and esc[ii” isbound to insertthetext Function Key i.Thefull set of escape sequences is 

\c- Control prefix 

\m- Meta prefix 

\e An escape character 

u Backslash 

v Literal" 

Y Literal ‘ 
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W hen entering thetext of a macro, singleor double quotes should be used to indicate a macro definition. U nquoted text is 

assumed to be a function name Backslash will quote any character in the macro text, including" and 

bash allows the current readiine key bindings to be displayed or modified with the bind built-in command. The editing 

mode may be avitched during interactive use by using the -o option to the set built-in command. (See "Shell Built-in 

Commands.") 

Readline has variables that can be used to further customize its behavior. A variable may beset in the inputrc file with a 
statement of the form: 
set variable-name value 


Except where noted, readiine variables can take the values on or oft. The variables and their default values are as follows 


horizontal-scroll-mode(Off) 

editing-mode (emacs) 
mark-modified-lines (Off) 
bell-style (audible) 

comment-begin ("#") 
meta-flag (Off) 

convert-meta (On) 

output-meta (Off) 
completion-query-items(100) 


keymap(emacs) 


show-all-if-ambiguous (Off) 

expand-tilde(Off) 


When set to on, makes readiine use a single linefor display, scrolling the input 
horizontally on a single screen line when it becomes longer than the screen width 
rather than wrapping to a new line 

Controls whether readiine begins with a set of key bindings similar to emacs or vi. 
editing-mode Can beS0t to either emacs Or vi. 

If set to on, history lines that have been modified are displayed with a preceding 
asterisk (*). 

C ontrols what happens when readiine wants to ring the terminal bell. If set to none, 
readiine never rings the bell. If set to visible, readiine uses a visible bell if one is 
available. If set to audible, readiine attempts to ring the terminal's bell. 

Thestring that is inserted in vi mode when the vi-comment command isexecuted. 

If set to on, readiine will enable eight-bit input (that is, it will not strip the high bit 
from the characters it reads), regardless of what the terminal claims it can support. 

If set to on, readiine will convert characters with the eighth bit set to an ASC11 key 
sequence by stripping the eighth bit and prepending an escape character (in effect, 
using escape as the meta prefix). 

If set to on, readiine will display characters with the eighth bit set directly rather 
than as a meta-prefixed escape sequence 

This determines when the user is queried about viewing the number of possible 
completions generated by the possible-completions command. It may be set to any 
integer value greater than or equal to zero. If the number of possible completions is 
greater than or equal to the value of this variable, the user is asked whether or not he 
wishes to view them; otherwise they are simply listed on the terminal. 

Set the current readiine keymap. The set of legal keymap names is emacs, emacs- 
standard, emacs-meta, emacs-ctlx, vi, vi-move, vi-command, and vi-insert. vi is 
equivalent to Vi-command; emacs is equivalent to emacs-standard. The default value is 
emacs; the value of editing-mode also affects the default keymap. 

This alters the default behavior of the completion functions If set to on, words 
which have more than one possible completion cause the matches to belisted 
immediately instead of ringing the bell. 

If set to on, tilde expansion is performed when readiine attempts word completion. 


Readiine implements a facility similar in spirit to the conditional compilation features of the C preprocessor that allows key 
bindings and variable settings to be performed as the result of tests. There are three parser directives used. 

$if T he $if construct allows bindings to be made based on the editing mode the 

terminal being used, or the application using readiine. Thetext of the test extends 
to the end of the line; no characters are required to isolate it. 



mode The mode= form of the$if directive is used to test whether 

readiine is in emacs or vi mode This may be used in conjunction 
with the set keymap command, for instance, to set bindings in the 
emacs-standard and emacs-ctlx keymapsonly if readline iSStarting 
out in emacs mode 

term Theterm= form may be used to include terminal-specific key 

bindings, perhaps to bind the key sequences output by the 
terminal's function keys The word on the right sideof the = is 
tested against the full name of the terminal and the portion of the 
terminal name before the first-. This allows sun to match both 
sun and sun-cmd, for instance. 

application T he application construct is Used to include application-specific 
settings Each program using the readiine library setsthe 
application name, and an initialization file can test for a particular 
value. Thiscould be used to bind key sequences to functions 
useful for a specific program. For instance the following 
command adds a key sequence that quotes the current or previous 
word in bash: 

# Quote the current or previ oils word 
"\C-xq": "\eb\"\ef\"" 

$endif 

$endif This command, as shown in the preceding example, terminates an $if command. 

$eise Commands in this branch ofthe$if directive are executed if the test fails 

readiine commands may be given numeric arguments which normally act asa repeat count. Sometimes, however, it isthe 
sign of the argument that issignificant. Passing a negative argument to a command that actsin theforward direction (such as 
kin-line) causes that command to act in a backward direction. Commands whose behavior with arguments deviates from 
this are noted. 

When a command isdescribed as killing text, the text deleted issaved for possible future retrieval (yanking). The killed text 
issaved in a kill-ring. Consecutive kills cause the text to be accumulated intooneunit, which can be yanked all at once 
C ommands that do not kill text separate the chunks of text on the kill- ring. 

Thefollowing isa list of the names of the commands and the default key sequences to which they are bound. 


C ommands for M oving 
beginning-of-line(C-a) 
end-of-line (C-e) 
forward-char(C-f) 
backward-char(C-b) 
forward-word(M-f) 

backward-word (M-b) 
clear-screen(C-l) 
redraw-current-line 


M oveto the start of the current line. 

M ove to the end of the line 
M ove forward a character. 

M ove back a character. 

M ove forward to the end of the next word. Words are composed of alphanu¬ 
meric characters (letters and digits). 

M ove back to the start of this, or the previous, word. W ords are composed of 
alphanumeric characters (letters and digits). 

Clear the screen leaving the current line at thetop of the screen. With an 
argument, refresh the current line without clearing the screen. 

Refresh the current line By default, this is unbound. 
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C ommands for M anipulating the H i story 


accept-line (Newline, Return) 


previous-history(C-p) 
next-history(C-n) 
beginning-of-history (m-<) 
end-of-history( m->) 
reverse-search-history(C-r) 

forward-search-history(C-s) 

non-incremental-reverse- 
search-history (M-p) 
non-incremental-forward- 
search-history (M-n) 
history-search-forward 


history-search-backward 


yank-nth-arg(M-C-y) 


yank-last-arg (m-., M-J 
shell-expand-line(M-C-e) 


history-expand-line (M-“) 
insert-last-argument (M-., M-_) 
operate-and-get-next (C-o) 


Accept the line regardless of where the cursor is. Ifthis line is non-empty, add it 
to the history list according to thestate of the hist-control variable. If the line is 
a modified history line, then restore the history line to its original state 
Fetch the previous command from the history list, moving back in the list. 

Fetch the next command from the history list, moving forward in the list. 

M ove to thefirst line in the history. 

M ove to the end of the input history, that is, the line currently being entered. 
Search backward starting at the current line and moving "up" through the 
history as necessary. Thisisan incremental search. 

Search forward starting at the current line and moving "down" through the 
history as necessary. Thisisan incremental search. 

Search backward through the history, starting at the current line using anon- 
incremental search for a string supplied by the user. 

Search forward through the history using a nonincremental search for a string 
supplied by the user. 

Search forward through the history for the string of characters between the start 
of thecurrent line and thecurrent point. Thisisa nonincremental search. By 
default, this command is unbound. 

Search backward through the history for thestring of characters between the start 
of the current line and thecurrent point. Thisisa nonincremental search. By 
default, this command is unbound. 

Insert thefirst argument to the previous command (usually the second word on 
the previous line) at point (thecurrent cursor position). With an argument n, 
insert the n th word from the previous command (the words in the previous 
command begin with word 0). A negative argument inserts the nth word from 
the end of the previous command. 

Insert the last argument to the previous command (the last word on the previous 
line). With an argument, behave exactly like @codefyank-nth-argg. 

Expand the line the way the shell does when it reads it. This performs alias and 
history expansion as well as all of theshell word expansions See "FI istory 
Expansion," later in this manual page, for a description of history expansion. 
Perform history expansion on thecurrent line See "FI istory Expansion." 

A synonym for yank-last-arg. 

Accept thecurrent linefor execution and fetch the next line relative to the 
current linefrom the history for editing. Any argument is ignored. 


C ommands for C hanging T ext 

delete-char (C-d) 

backward-delete-char(Rubout) 

quoted-insert (C-q, C-v) 

tab-insert (C-v Tab) 
self-insert (a, b, A, 1 , !, ...) 


D elete the character under the cursor. If point is at the beginning of the line, 
there are no characters in the line, and the last character typed was not c-d, then 
return eof. 

D elete the character behind the cursor. W hen given a numeric argument, save 
the deleted text on the kill-ring. 

Add the next character that you type to the line verbatim. This is how to insert 
characters like c-q, for example. 

Insert a tab character. 

I nsert the character typed. 



transpose-chars(C-t) 

D rag the character before point forward over thecharacter at point. Point moves 
forward as well. If point is at the end of the line then transpose the two 
characters before point. N egative arguments don't work. 

transpose-words(M-t) 

D rag the word behind the cursor past the word in front of the cursor, moving 
the cursor over that word as well. 

upcase-word (m-u) 

U ppercase the current (or following) word. W ith a negative argument, do the 
previous word, but do not move point. 

downcase-word (M-l) 

Lowercase the current (or following) word. With a negative argument, do the 
previous word, but do not move point. 

capitalize-word( m-c) 

Capitalize the current (or following) word. With a negative argument, do the 
previous word, but do not move point. 

Killing and Yanking 


kill-line (C-k) 

Kill the text from the current cursor position to the end of the line. 

backward-kill-line(C-x C-Rubout) 

Kill backward to the beginning of the line 

UNIX-line-discard(C-u) 

Kill backward from pointto the beginning of the line. 

kill-whole-line 

Kill all characters on the current line no matter where the cursor is By default, 
this is unbound. 

kill-word (M -d) 

Kill from the cursor to the end of the current word, or if between words, to the 
end of the next word. Word boundaries are the same as those used bytorward- 

backward-kill-word(lul-Rubout) 

K ill the word behind the cursor. Word boundaries are the same as those used by 


backward-word. 

UNIX-word-rubout(C-w) 

Kill the word behind the cursor, using whitespace as a word boundary. The word 
boundaries are different from backward-kiii-word. 

delete-horizontal-space 

Delete all spaces and tabs around point. By default, thisisunbound. 

yank(C-y) 

Yank the top of the kill ring into the buffer at the cursor. 

yank-pop (M-y) 

Rotate the kill-ring, and yank the new top. Only worksfollowing yank or yank- 
pop. 

Numeric Arguments 


digit-argument (M- 0 , M- 1 , ..., M—) 

Add this digit to the argument already accumulating, or start a new argument. 


m— starts a negative argument. 

universal-argument 

Each time this is executed, the argument count is multiplied by four. The 
argument count is initially one so executing thisfunction thefirst time makes 
the argument count four. By default, this is not bound to a key. 

Completing 


complete (tab) 

Attempt to perform completion on the text before point. Bash attempts 
completion treati ng the text as a vari able (if the text begins with $), username (if 
the text beginswith '), hostname (if the text begins with @), or command 
(including aliases and functions) in turn. If none of these producesa match, 
filename completion isattempted. 

possible-completions (m-?) 

List the possible completions of the text before point. 

insert-completions 

Insert all completions of the text before point that would have been generated by 
possible-completions. By default, this is not bound to a key. 

complete-filename (m-/) 

Attempt filename completion on the text before point. 
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Completing 

possible-filename-completions(C-x /) 
complete-username( m-‘) 
possible-username-completions(C-x ") 
complete-variable( m-$) 
possible-variable-completions(C-x $) 

complete-hostname( m-@) 
possible-hostname-completions(C-x @) 
complete-command(M-!) 


possible-command-completions(C-x i) 
dynamic-complete-history (m-TAB) 
complete-into-braces (m-{) 


List the possible completions of the text before point, treating it as a filename. 
Attempt completion on the text before point, treating it asa username 
List the possible completions of the text before point, treating it asa username. 
Attempt completion on the text before point, treating it as a shell variable 
List the possible completions of the text before point, treating it as a shel I 
variable 

Attempt completion on the text before point, treating it as a hostname 
List the possible completions of the text before point, treating it as a hostname. 
Attempt completion on the text before point, treating it as a command name. 
Command completion attempts to match the text against aliases, reserved words, 
shell functions, builtins, and finally executable filenames, in that order. 

List the possible completions of the text before point, treating it asa command 
name 

Attempt completion on the text before point, comparing the text against lines 
from the history list for possible completion matches 
Perform filename completion and return the list of possible completions enclosed 
within bracesso thelist is available to theshell. (See "Brace Expansion," earlier in 
this manual page.) 


Keyboard M acros 


loro (C-x () 
'0 (C-x )) 


call-last-kbd- 


e) 


Begin saving the characters typed into the current keyboard macro. 

Stop saving thecharacters typed into thecurrent keyboard macro and save the 
definition. 

Re-execute the last keyboard macro defined, by making the characters in the 
macro appear as if typed at the keyboard. 


M isrdlaneous 

re-read-init-file(C-x C-r) 


abort(C-g) 

do-uppercase-version (M-a, M-b, ...) 
prefix-meta (ESC) 
undo (C-_, C-x C-u) 
revert-line (M-r) 

tilde-expand( m-‘) 
dump-functions 


display-shell-version (C-x C-v) 
emacs-editing-mode(c-e) 


Read in the contents of your init file and incorporate any bindings or variable 
assignments found there. 

Abort the current editing command and ring the terminal’s bell (subject to the 
setting of bell-style). 

Run the command that is bound to the corresponding uppercase character. 

M etafy the next character typed. ESC-f isequivalent to M eta-f. 

Incremental undo, separately remembered for each line. 

Undo all changes made to this line. This islike typing the undo command 
enough times to return the line to its initial state 
Perform tilde expansion on the current word. 

Print all of the functions and their key bindings to the readiine output stream. If 
a numeric argument is supplied, the output is formatted in such a way that it can 
be made part of an inputrc file. 

D isplay version information about the current instance of bash. 

When in vi editing mode thiscauses a switch to emacs editing mode. 


HISTORY 

When interactive, theshell provides access to the command history, thelist of commands previously typed. The text of the 
lastHiSTsizE commands (default 500) issaved in a history list. Theshell stores each command in the history list prior to 
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parameter and variable expansion (see "Expansion," earlier in this manual page) but after history expansion is performed, 
subject to the values of the shell variables command_oriented_history and histcontrol. On startup, the history is initialized 
from the file named by the variable histfile (default '/.bashjiistory). HI ST FILE is truncated, if necessary, to contain no 
more than histfilesize lines. The built-in command fc (see Shell Built-in Commands, later in this manual page) maybe 
used to list or edit and re-execute a portion of the history list. The history builtin can be used to display the history list and 
manipulate the history file. When using the command-line editing, search commands are available in each editing mode that 
provide access to the history list. W hen an interactive shell exits, the last histsize lines are copied from the history list to 
histfile. If histfile is unset, or if the history file is unwritable, the history is not saved. 

HISTORY EXPANSION 

The shell supports a history expansion feature that is similar to the history expansion in csh. This section describes what 
syntax features are available This feature is enabled by default for interactive shells, and can be disabled using the h option to 
the set built-in command. (See "Shell Built-in Commands," later in this manual page.) Noninteractive shells do not perform 
history expansion. 

H istory expansion is performed immediately after a complete line is read, before the shell breaks it into words It takes place 
in two parts. T he first is to determine which line from the previous history to use during substitution. Thesecond is to select 
portions of that li ne for i ndusion into the current one. T he I ine selected from the previous history is the event, and the 
portions of that line that are acted upon are words. The line is broken into words in the same fashion as when reading input, 
so that several metacharacter-separated words surrounded by quotes are considered as one word. Only the backslash (\) and 
single quotes can quote the history escapecharacter, which is i by default. 

Theshell allows control of the various characters used by the history expansion mechanism. (See the description of histchars 
under "Shell Variables," earlier in this manual page.) 

EVENT DESIGNATORS 

An event designator is a reference to a command line entry in the history list. 
i Start a history substitution, except when followed by a blank, newline, =, or (. 

!! Refer to the previous command. This isa synonym for i-i. 

in Refer to command linen. 

!-n Refer to the current command line minus n. 

'string Refer to the most recent command starting with string. 

t?st r i ng [?] Refer to the most recent command containing st r i ng. 

*stri ngi'stri ng 2 “ Q uick substitution. Repeat the last command, replacing st r i ngi with stri ng 2 . Equivalent to u-.si 
stri ngi/stri ng 2 /. (See"M odifiers," later in this manual page.) 
t# Theentirecommandlinetypedsofar. 

WORD DESIGNATORS 

A colon (:) separates the event specification from the word designator. It can be omitted if the word designator begins with a 
", $, *, or%. Words are numbered from the beginning of the line, with thefirstword being denoted by a 0 (zero). 

0 (zero) Thezeroth word. For theshell, this isthe command word, 

n The nth word. 

Thefirstargument.Thatis,word 1. 

$ The last argument. 

% The word matched by the most recent ?stnng? search, 

x-y A range of words; -y abbreviates 0 -y. 

* All of the words but the zeroth. This is a synonym for 1-$. It is not an error to use* if there is just 

one word in the event; the empty string isreturned in that case 
x* Abbreviates x-$. 

x- Abbreviates x-$ like x*, but omitsthe last word. 
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MODIFIERS 

After the optional word designator, you can add a sequence of one or more of the following modifiers, each preceded by a : 
h Removeatrailingpathnamecomponent, leaving only the head, 

r Removeatrailingsuffixof theform ,*x*, leaving the basename. 

e Remove all but the trailing suffix, 

t Removeall leadingpathnamecomponentsjeavingthetail. 

p Print the new command but do not execute it. 

q Quote the substituted words, escaping further substitutions 

x Quote the substituted words as with q, but break into wordsat blanks and newlines, 

s/oi d /new/ Substitute new for the first occurrence of o i d in the event line Any delimiter can be used in place of 

/. Thefinal delimiter is optional if it is the last character of the event line The deli miter may be 
quoted in old and new with a single backslash. If & appearsin new, it is replaced by o i d. A single 
backslash will quote the&. 

& Repeattheprevioussubstitution. 

g Cause changesto be applied over the entire event line. This is used in conjunction with :s (for 

example, :gs/oi d/new/) or If used with :s, any delimiter can be used in place of /, and thefinal 
delimiter is optional if it is the last character of thee/ent line. 

ARITHMETIC EVALUATION 

Theshell allows arithmetic expressions to be evaluated, under certain circumstances. (Seetheiet built-in command and 
"Arithmetic Expansion.") Evaluation isdonein long integers with no check for overflow, though division by 0 is trapped and 
flagged as an error. Thefollowing list of operators isgrouped into levels of equal-precedence operators. The levels are listed 
in order of decreasing precedence. 

Unary minus and plus 
Logical and bitwise negation 
M ultiplication, division, remainder 
Addition, subtraction 
Left and right bitwise shifts 
Comparison 
Equality and inequality 
Bitwise and 
Bitwise exclusive or 
Bitwise or 
Logical and 
Logical or 

=&=“=!= Assignment 

Shell variables are allowed asoperands; parameter expansion is performed before the expression isevaluated. The value of a 
parameter is coerced to a long integer within an expression. A shell variable need not have its integer attribute turned onto 
be used in an expression. 

Constants with a leading 0 are interpreted as octal numbers. A leading ox or ox denotes hexadecimal. Otherwise, numbers 
take theform [base#]n, where base is a decimal number between 2 and 36 representing the arithmetic base and n isa 
number in that base. If base is omitted, then base 10 is used. 

0 perators are evaluated in order of precedence. Subexpressions in parentheses are evaluated first and may override the 
precedence rules 
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SHELL BUILT-IN COMMANDS 

No effect; the command does nothing beyond expanding arguments and performing 
any specified redirections A zero exit code is returned. 

Read and execute commands from fi i ename in the current shell environment and 
return the exit status of the last command executed from f i i e n a me. I f f i i e n a me does 
not contain a slash, pathnamesin path are used to find thedirectory containing 
filename. The file searched for in path need not be executable. The current directory 
is searched if no file is found in path. If any arguments are supplied, they become the 
positional parameters when tile isexecuted. Otherwise, the positional parameters 
are unchanged. The return status is the status of the last command exited within the 
script (0 if no commands are executed), and False if filename is not found, 
alias with no arguments prints the list of aliases in theform name=vai ue on standard 
output. When arguments are supplied, an aliasis defined for each name whose value 
is given. A trailing space in value causes the next word to be checked for alias 
substitution when the alias is expanded. For each name in the argument list for 
which no value is supplied, the name and value of the alias is printed, alias returns 
True unless a name is given for which no alias has been defined. 

Place j obs pec in the background, as if it had been started with &. If j obs pec is not 
present, the shell's notion of the current job is used, bg jobspec returns 0 unless run 
when job control is disabled or, when run with job control enabled, if jobspec was 
not found or started without job control. 

D isplay current readiine key and function bindings, or bind a key sequence to a 
readiine function or macro. The binding syntax accepted is identical to that of 
.inputrc, but each binding must be passed as a separate argument; for example, 
"\c-x\c-r": re-read-init-fiie. Options, if supplied, havethefollowing meanings: 

-m k e y ma p U se k e y ma p as the keymap to be affected by the subsequent 

bindings. Acceptable key map names are emacs, emacs-standard, 
emacs-meta, emacs-ctlx, vi, vi-move, vi-command, and vi-insert. 
vi is equivalent to vi-command; emacs is equivalent to emacs- 
standard. 

-1 List the names of all readiine functions. 

-v List current function names and bindings 

-d Dump function names and bindings in such away that they 

can be reread. 

-t filename Read key bindingsfrom filename 
-q function Q uery about which keys invokethe named function. 

The return value is 0 unless an unrecognized option is given or an error occurred, 
break [n] Exit from within a for, while, or until loop. If n isspecified, break n levels, n must 

be 1. If n is greater than the number of enclosing loops, all enclosing loops are 
exited. The return value is 0 unless the shell is not executing a loop when break is 
executed. 

buiitin shei 1 - bui 11 i n [arguments] Execute the specified shell builtin, passing it arguments, and return its exit status 
This is useful when you wish to define a function whose name is the same as a shell 
builtin, but need the functionality of the builtin within thefunction itself. The cd 
builtin iscommonly redefined this way. The return statusisFaise ifshei 1 -bui 1 ti n is 
not a shell builtin command. 

cd [dir] Change the current directory to di r. The variable home is the default d r. The 

variable cdpath defines the search path for the directory containing dir. Alternative 
directory names are separated by acolon (:). A null directory namein cdpath isthe 
same as the current directory, that is, (.). If di r begins with a slash (/), then cdpath is 
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command [ - pVv] c omman£ [arg ... ] 


declare [-frxi] [name[=v a I lie]] 
typeset [-frxi] [name[=val ue]] 


not used. An argument of - is equivalent to $oldpwd. The return value is True if the 
directory was successfully changed; False otherwise. 

Run command with args suppressing the normal shell function lookup. Only built- 
in commands or commands found in the path are executed. If the -p option isgiven, 
the search for command is performed using a default value for path that is guaranteed 
to find all of the standard utilities. If either the -v or -v option is supplied, a 
description of command is printed. The -v option causes a single word indicating the 
command or pathname used to invoke command to be printed; the -v option 
produces a more verbose description. An argument of -disables option checking for 
the rest of the arguments. If the-v or -v option issupplied, the exit status iso if 
command was found, and i if not. If neither option issupplied and an error occurred 
or command cannot be found, the exit status is 127. Otherwise, the exit status of the 
command builtin is the exit status of c 0 mma nd. 

Resume the next iteration of the enclosing for, while, or until loop. If n is specified, 
resume at the nth enclosing loop, n must be 1. If n is greater than the number of 
enclosing loops, the last enclosing loop (the top-level loop) is resumed. The return 
value ise unless theshell is not executing a loop when continue isexecuted. 

D eclare variables and/or give them attributes If no names are given, then display the 
values of variables instead. The options can be used to restrict output to variables 
with the specified attribute. 

-f Usefunction namesonly. 

-r Make names read-only. These names cannot then be assigned 

values by subsequent assignment statements 
-x M ark namesfor export to subsequent commands via the 

environment. 

-i T he variable istreated as an integer; arithmetic evaluation (see 

"Arithmetic Evaluation") is performed when the variable is 
assigned a value. 

U sing + instead of- turnsoff the attribute instead. When used in afunction, makes 
names local, as with the local command. The return value iso unless an illegal 
option is encountered, an attempt ismadeto define a function using 11 -f foo=bar\ 
oneof the names is not a legal shell variable name, an attempt is made to turn off 
read-only status for a read-only variable, or an attempt is made to display a 
nonexistent function with -f. 

D isplay the list of currently remembered directories. D irectories are added to the list 
with the pushd command; the popd command moves back up through the list. 

+n D isplaysthe nth entry counting from the left of the list shown 

by dirs when invoked without options, starting with zero. 

-n D isplaysthe nth entry counting from the right of the list 

shown by dirs when invoked without options, starting with 
zero. 

-1 Producesa longer listing; the default listing format uses a tilde 

to denote the home directory. 

The return value iso unless an illegal option issupplied or n indexes beyond the end 
of the directory stack. 

Output the args, separated by spaces The return status is always 0. If -n isspecified, 
the trailing newline issuppressed. If the -e option isgiven, interpretation of the 
following backslash-escaped characters is enabled. The-E option disables the 
interpretation of these escape characters even on systems where they are interpreted 
by default. 
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\a Alert (bell) 

\b Backspace 

\c Suppresstrailing newline 

\f Formfeed 

\n Newline 

\r Carriage return 

\t H orizontal tab 

\v Vertical tab 

u Backslash 

twn The character whose ASCI I codeisnnn (octal) 

enable [-n][-aii] [name ...] Enableand disablebuiltin shell commands.Thisallowstheexecution of adisk 

command that has the same nameas a shell builtin without specifying a full 
pathname. If -n is used, each name is disabled; otherwise names are enabled. For 
example, to use the test binary found via the path instead of the shell builtin version, 
type enable -n test. If no arguments are given, a list of all enabled shell builtinsis 
printed. If only -n issupplied, a list of all disabled builtinsis printed. If only -all is 
supplied, the list printed includes all builtins, with an indication of whether or not 
each is enabled, enable accepts -a asasynonym for -an. The return value iso unless 
a name is not a shell builtin. 

evai [arg ...] Theargs areread and concatenated together into a single command. Thiscommand 

is then read and executed by the shell, and its exit status is returned as the value of 
the evai command. If there are no args, or only null arguments, evai returns True, 
exec [[-] command [arguments]] If command isspecified, it replaces theshell. N o new process iscreated. The arguments 
become the arguments tocommand. Ifthe first argument is-,theshell placesadash in 
the zeroth arg passed to command. This is what login does If thefile cannot be 
executed for some reason, a noninteractive shell exits unless the shell variable 
no_exit_on_faiied_exec exists in which case it returns failure. An interactive shell 
returns failure if the file cannot be executed. If command is not specified, any 
redirections take effect in the current shell, and the return status iso. 
exit [n] C ause the shell to exit with a status of n. If n isomitted, the exit status is that of the 

last command executed. A trap on exit isexecuted before the shell terminates, 
export [-nt ] [name [=wo r d ] ] ... Thesupplied namesare marked for automatic export to the environment of 

export -p subsequently executed commands. If the -f option isgiven, the names refer to 

functions If no names are given, or if the -p option issupplied, a list of all names 
that are exported in this shel I is printed. T he -n option causes the export property to 
be removed from the named variables. An argument of - disablesoption checking 
for the rest of the arguments, export returnsan exit status of 0 unless an illegal 
option is encountered, one of the names is not a legal shell variable name, or-f is 
supplied with a name that is not a function. 

fc [-e ename ] [-nir] [f i r s t ] [i as t ] Fix command. I n the first form, a range of commands from f i r st to 1 as t is selected 

fc -s [pat =r ep ] [c md ] from the history list, f i rst and last may be specified as a string (to locate the last 

command beginning with that string) or asa number (an index into the history list, 
where a negative number is used as an offset from the current command number). If 
last is not specified, it is sdt to the current command for listing (so that fc -1 
-10 prints the last 10 commands) and to first otherwise. If first isnot specified, it 
is set to the previous command for editing and -16 for listing. 

The-n flag suppresses the command numbers when listing. The -r flag reverses the 
order of the commands If the-1 flag isgiven, the commands are listed on standard 
output. 0 therwise the editor given by ename is invoked on a file containing those 
commands If ename isnot given, the value of the fcedit variable is used, and the 
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value of editor if fcedit is not set. If neither variable is set, vi is used. When editing 
is complete, the edited commands are echoed and executed. 

I n the second form, c o mma n d is reexecuted after each instanceof pat is replaced by 
rep. A useful alias to use with this is r=fc -s, so that typing r cc runsthe last 
command beginning with cc and typing r reexecutes the last command. 

If the first form is used, the return value is@ unless an illegal option isencountered 
or f i r st oriast specify history lines out of range. If the-e option issupplied, the 
return value isthevalue of the last command executed or failure if an error occurs 
with thetemporary file of commands. If the second form is used, the return status is 
that of the command reexecuted, unless and does not specify a valid history line, in 
which casetc returnsfailure. 

fg [j obs pec ] Placej obs pec in the foreground, and make it the current job. If j obs pec isnot 

present, the shell's notion of the current job is used. The return value is that of the 
command placed into the foreground, or failure if run when job control is disabled 
or, when run with job control enabled, if j obs pec does not specify a valid job or 
j obspec specifies a job that was started without job control. 

getopts opt st r i ng name [args] getopts is used by shell procedures to parse positional parameters opt st r i ng contains 

the option letters to be recognized; if a letter isfollowed by a colon, the option is 
expected to have an argument, which should be separated from it by whitespace 
Each time itisinvoked, getopts pi aces the next option in theshell variable name 
initializing n a me if it does not exist, and the index of the next argument to be 
processed into the variable optind. optind isinitialized to i each time the shell or a 
shell script is invoked. When an option requires an argument, getopts places that 
argument into the variable optarg. Theshell does not reset optind automatically; it 
must be manually reset between multiple calls to getopts within thesame shell 
invocation if a new set of parameters isto be used. 

getopts can report errors in two ways. If thefirst character ofoptstri ng isacolon, 
silent error reporting is used. In normal operation, diagnostic messages are printed 
when illegal options or missing option arguments are encountered. If the variable 
opterr is set to 0, no error message will be displayed, even if thefirst character of 
opt str i ng isnotacolon. 

If an illegal option isseen, getopts places a question mark (?) into name and, if not 
silent, prints an error message and unsets optarg. If getopts issilent, the option 
character found isplaced in op-targ and no diagnostic message is printed. 

If a required argument is not found, and getopts is not silent, a question mark (?) is 
placed in name, optarg is unset, and a diagnostic message is printed. If getopts is 
silent, then acolon (:) isplaced in name and optarg is set to the option character 
found. 

getopts normally parses the positional parameters, but if more arguments are given 
in args, getopts parses those instead, getopts returns True if an option, specified or 
unspecified, isfound. It returnsFaise if the end of options is encountered or an error 
occurs. 

hash [-r] [name ] For each name, thefull pathnameof the command isdetermined and remembered. 

The -r option causes the shell to forget all remembered locations If no arguments 
are given, information about remembered commands is printed. An argument of - 
disables option checking for the rest of the arguments. The return status isTrue 
unless a name is not found or an illegal option issupplied. 

help [pattern] D isplay helpful information about built-in commands If pat t er n is specified, help 

gives detailed help on all commands matching pattern; otherwise, a list of the 
builtins is printed. The return status is 0 unless no command matches pattern. 
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history [n] 
history -rwan 




kill [-s sigspec | -sigspec] 
[pi d | j obspec ] ... 
kill -1 [si gnum] 


let arg [arg ... ] 
local [name[=vaI ue ] 


logout 
popd [+/-n] 


With no options, display the command history list with line numbers. Lines listed 
with a* have been modified. An argument of n lists only the last n lines If a 
nonoption argument is supplied, it is used as the name of the history file; if not, the 
value of histfile isused. Options, if supplied, have thefollowing meanings 

-a Append the "new" history lines (history linesentered sincethe 

beginning of the current bash session) to the history file. 

-n Read the history lines not already read from the history file 

into the current history list. These are lines appended to the 
history file since the beginning of the current bash session. 

-r Read the contents of the history file and use them asthe 

current history. 

w- Write the current history to the history file, overwriting the 

history file's contents. 

The return value iso unless an illegal option is encountered or an error occurs while 
reading or writing the history file. 

Thefirst form lists the active jobs. T he -1 option lists process ID sin addition to 
the normal information; the -p option lists only the process ID of the job's process 
group leader. The-n option displays only jobs that have changed status since last 
notified. I f j o bs pec is given, output is restricted to information about that job. The 
return status is e unless an illegal option isencountered or an illegal j obs pec is 
supplied. 

If the-x option issupplied, jobs replaces any] obs pec found in command orargs with 
the correspondi ng process group ID, and executes command, passing it ar gs, returning 
its exit status 

Send the signal named by sigspec to the processes named bypid orjobspec.sigspec 
iseither a signal namesuch assiGKiLLorasignal number. If si gs pec isa signal 
name the name is not case sensitive and may be given with or without the sig 
prefix. If sigspec is not present, then sigterm is assumed. An argument of -1 liststhe 
signal names If any arguments are supplied when -1 is given, the names of the 
specified signals are listed, and thereturn status is 0. An argument of - disables 
option checking for the rest of the arguments kill returns True if at least one signal 
was successfully sent, or False if an error occurs or an illegal option isencountered. 
Each arg isan arithmetic expression to be evaluated. (See "Arithmetic Evaluation.") 
If the last arg evaluates to 0, let returns 1; 0 is returned otherwise. 

For each argument, createa local variablenamed name, and assign it vai ue. When 
local isused within afunction, it causes the variable name to have a visible scope 
restricted to that function and its children. W ith no operands, local writes a list of 
local variables to thestandard output. It isan error to use local when not within a 
function. Thereturn status iso unless local isused outside a function, or an illegal 
name is supplied. 

Exit a login shell. 

Removes entries from the directory stack. W ith no arguments, removes the top 
directory from the stack, and performs a cd to the new top directory. 

+n Removes the nth entry counting from the left of the list shown 

by dirs, starting with zero. For example, popd +0 removes the 
first directory, popd +1 thesecond. 

-fi Removesthenth entry counting from the right of the list 

shown by dirs, starting with zero. For example, popd -0 
removesthe last directory, popd -1 the next to last. 
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pushd [dir] pushd +/-n 


readonly [-f] [name ...] 
readonly -p 


set [-abefhkmnptuvxldCHP] 
[-0 option][arg ...] 


If the popd command is successful, a dirs is performed as well, and the return status 
iso. popd returns False if an illegal option isencountered, the directory stack is 
empty, a nonexistent directory stack entry is specified, or the directory change fails. 
Adds a directory to thetop of the directory stack, or rotates the stack, making the 
new top of the stack the current working directory. With no arguments, exchanges 
thetop two directories and returnso, unlessthedirectory stack isempty. 

+n Rotates the stack so that the nth directory (counting from the 

left of the list shown by dirs) is at thetop. 

4 ’ Rotates the stack so that the nth directory (counting from the 

right) is at the top. 

dir Adds dir to the directory stack at the top, making it the new 

current working directory. 

If the pushd command issuccessful, adirs isperformed as well. If thefirst form is 
used, pushd returnso unless the cd to di r fails. With the second form, pushd returnso 
unless thedirectory stack isempty, a nonexistent directory stack element is specified, 
or the directory change to the specified new current directory fails. 

Print the absolute pathname of the current working directory. T he path printed 
contains no symbolic links if the -p option to the set builtin command is set. (See 
also the description of nolinks under "Shell Variables," earlier in thismanual page) 
The return status iso unless an error occurs while reading the pathname of the 
current directory. 

One line is read from the standard input, and the first word is assigned to thefirst 
name the second word to the second name, and so on, with leftover words assigned 
to the last name. 0 nly the characters in ifs are recognized as word delimiters. If no 
names are supplied, the line read is assigned to the variable reply. T he return code is 
zero, unlessend-of-file isencountered. Ifthe -roption isgiven, a backslash-newline 
pair is not ignored, and the backslash is considered to be part of the line. 

Thegiven names are marked readonly and the values of these names may not be 
changed by subsequent assignment. Ifthe-f option issupplied, the functions 
corresponding to the names are so marked. If no arguments are given, or if the 
-p option issupplied, a list of all readonly names is printed. An argument of - 
disables option checking for the rest of the arguments. The return status isa unless 
an illegal option isencountered, one of the names is not a legal shell variable name, 
or-f issupplied with a name that is not a function. 

C auses a function to exit with the return value specified by n. If n is omitted, the 
return statusisthat of the last command executed in thefunction body. Ifused 
outside a function, but during execution of a script by the . (source) command, it 
causes the shell to stop executing that script and return either n or the exit status of 
the last command executed within the script as the exit status of the script. Ifused 
outside a function and not during execution of a script by (. , the return status is 
False. 


-a Automatically mark variables that are modified or created for 

export to the environment of subsequent commands 
-b C ause the status of termi nated background jobs to be reported 

immediately, rather than before the next primary prompt. 
(Also see notify under "Shell Variables") 

-e Exit immediately if a simple command (see "Shell Grammar," 

earlier in this manual page) exits with a non-zero status. The 
shell does not exit if the command that fails is part of an until 



or while loop, part of an it statement, part of a && or 11 list, or 
if the command's return value is being inverted via i. 

Disable pathname expansion. 

Locate and remember function commands as functions are 
defined. F unction commands are normally looked up when 
thefunction isexecuted. 

All keyword arguments are placed in the environment for a 
command, not just those that precede the command name. 

M onitor mode Job control is enabled. This flag is on by 
default for interactive shells on systems that support it. (See 
"Job Control," earlier in this manual page) Background 
processes run in a separate process group and a line containing 
their exit status is printed upon their completion. 

Read commands but do not execute them. This may be used 
to check a shell script for syntax errors This is ignored for 
interactive shells 

T he o p t i o n ■ n a me can be one of the following: 
aiiexport— Sameas-a. 

braceexpand- The shell performs brace expansion. (See"Brace 

Expansion," earlier in this manual page.) Thisison by default. 

emacs—Usean emacs-style command line editing interface 

This is enabled by default when the shell is interactive unless 

theshell is started with the -noiineediting option. 

errexit—Sameas-e. 

histexpand— Same as -H. 

ignoreeof— The effect is as if the shell command 

1 ignoreeof=i o 1 had been executed. (See "Shell Variables") 

interactive-comments— Allow a word beginning with # to 

cause that word and all remaining characters on that line to be 

ignored in an interactive shell. (See "Comments," earlier in 

this manual page.) 

monitor— Same as -m. 

nociobbei — Same as -c. 

noexec— Sameas -n. 

nogiob- Sameas -f. 

nohash— Sameas -d. 

notify- Same as-b. 

nounset— Same as -u. 

physical— Same as -p. 

posix- C hange the behavior of bash where the default 
operation differs from the POSIX 1003.2 standard to match 
the standard, 
privileged— Same as -p. 
verbose— Same as -v. 

vi— U se a vi-style command line editing i nterface. 
xtrace— Sameas -X. 

If no o p t i o n ■ n a me is supplied, the values of the current options 
are printed. 
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-p Turn on privileged mode. In thismode, the $env fileisnot 

processed, and shell functions are not inherited from the 
environment. This is enabled automatically on startup if the 
effective user (group) ID is not equal to the real user (group) 

ID. T urning this option off causes the effective user and group 
ID s to be set to the real user and group ID s 
-t Exit after reading and executing onecommand. 

-u Treat unset variables as an error when performing parameter 

expansion. If expansion isattempted on an unset variable, the 
shell prints an error message, and, if not interactive, exits with 
a non-zero status. 

-v Print shell input linesastheyareread. 

-x After expanding each simple command, bash displaysthe 

expanded value of ps 4 , followed by the command and its 
expanded arguments. 

-l Saveand restorethe binding of name in a for name [in word] 

command. (See "Shell Grammar," earlier in this manual page) 
-d D isable the hashing of commandsthat are looked up for 

execution. N ormally, commands are remembered in a hash 
table, and once found, do not have to be looked up again. 

-c The effect is as if the shell command nociobber= had been 

executed. (See "Shell Variables") 

-h Enable i style history substitution. T hisflag ison by default 

when theshell is interactive 

-p If set, do not follow symbolic links when performing 

commandssuch ascd that change the current directory. The 
physical directory is used instead. 

If no arguments follow this flag, then the positional parameters 
are unset. 0 therwise, the positional parameters are set to the 
args, even if some of them begin with a -. 

Signal the end of options, cause all remaining args to be 
assigned to the positional parameters T he -x and -v options 
are turned off. If there are no args, the positional parameters 
remain unchanged. 

The flags are off by default unless otherwise noted. Using + 
rather than - causes these flags to be turned off. The flags can 
also be specified as options to an invocation of theshell. The 
current set of flags may be found in $-. After the option 
arguments are processed, the remaining n args are treated as 
values for the positional parameters and are assigned, in order, 
to $1, $2,... $n. If no options or args are supplied, all shell 
variables are printed. The return status is always True unless an 
illegal option is encountered. 

shift [n ] The positional parameters from n.+i ... are renamed to .... Parameters represented 

by the numbers $# down to $#-n+i are unset. If n is 0, no parameters are changed. If 
n is not given, it is assumed to bei. n must be a non-negative number less than or 
equal to $#. If n is greater than $#, the positional parameters are not changed. T he 
return status is greater than 0 if n isgreaterthan or less than 0; otherwise 0. 
suspend [-f] Suspend theexecution ofthisshell until it receivesasiG-coNT signal. The-f option 

says not to complain if this is a login shell; just suspend anyway. The return status is 



0 unless theshell isa login shell and -f is not supplied, or if job control is not 
enabled. 

Return a status of 0 (True) or 1 (False) depending on the evaluation of the 
conditional expression expr. Expressions may be unary or binary. U nary expressions 
are often used to examine the status of a file There are string operators and numeric 
comparison operators as well. Each operator and operand must be a separate 
argument. If file is of the form /dev/fd/n, then file descriptor n ischecked. 

-b f i 1 e— True iff i i e exists and is block special. 

-c f i 1 e— True iffiie exists and is character special. 

-d f i 1 e — True iffiie exists and isa directory. 

-e f i I e — True iff i I e exists 

-f file— True iffiie exists and isa regular file. 

-g f i 1 e— True iffiie exists and is set-group-id. 

-k file— True iffiie has its "sticky" bit sdt. 

-l file— True iffiie exists and is a symbolic link. 

-p file— True iffiie exists and is a named pipe. 

-r f i 1 e— True iff i i e exists and is readable. 

-s f i 1 e— True iff i i e exists and has a size greater than zero. 

-s f i 1 e— True iff i i e exists and isa socket. 

-t fd— True if f d isopened on a terminal. 

-u fi 1 e — True iff i i e exists and its set-user-id bit is set. 

-w f i 1 e— True iff i i e exists and is writable. 

-x f i 1 e— True iff i i e exists and is executable. 

-0 f i 1 e— True iff i i e exists and is owned by the effective user ID. 

-g file — True if f i i e exists and is owned by the effective group ID. 

fi 1 ei -nt f i 1 e2 — True iff i i ei isnewer (accordingto modification date) than 

fiI e2. 

f i 1 el -ot f i 1 e 2 — True if f i 1 el is Older than f I e 2. 

f i i ei -ef f i i e— True iff i i ei and f i i e2 have the same device and inode 

numbers. 

-z st r i ng— True if the length of st ri ng iszero. 

-n stri ng — True if the length of st ri ng isnon-zero. 
st r i ngi = stri ng2—True if the strings are equal, 
stri ngi t= stri ng2—True if the strings are not equal. 

! expr — True if expr iSFalse. 

expr 1 -a expr 2— True if both exprl AND ex pr 2 are True. 

expr 1 -o expr 2 — True if either expr 1 OR expr 2 is True. 

argi op ar g2 op isoneof -eq,-ne,-it,-ie,-gt, or -ge. These arithmetic binary 

operators return True if argi is equal, not-equal, less-than, less-than-or-equal, 

greater-than, or greater-than-or-equal than arg2, respectively. Argi and arg2 may 

be positive integers, negative integers, or the special expression -i string, which 

evaluates to the length ofstri ng. 

Print the accumulated user and system timesfor theshell and for processes run from 
theshell. The return status is 0. 

Thecommandarg is to be read and executed when theshell receives signal(s) 
si gspec. If arg isabsentor-, all specified signals are reset to their original values (the 
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values they had upon entrance to the shell). If ar g is the null string, this signal is 
ignored by theshdl and by the commands it invokes si gs pec iseither a signal name 
defined in <signai.h>, or a signal number. If s i gs pec is exit (0), thecommand ar g 
isexecuted on exit from theshell. With no arguments, trap printsthe list of 
commands associated with each signal number. The -1 option causes the shell to 
print a list of signal names and their corresponding numbers. An argument of - 
disables option checking for the rest of the arguments. Signals ignored upon entry to 
theshell cannot be trapped or reset. T rapped signals are reset to their origi nal values 
in a child process when it is created. The return status is False if either the trap name 
or number is invalid; otherwise, trap returnsTrue. 

type [-aii] [-type | -path] With no options, indicate how each name would be interpreted if used as a 

name [name ...] command name. If the -type flag is used, type prints a phrase that is one of alias, 

keyword, function, buiitin, or file if name is an alias, shell reserved word, function, 
builtin, or disk file respectively. If the name is not found, then nothing is printed, 
and an exit status of False is returned. If the -path flag is used, type either returns 
the name of thedisk file that would be executed if name were specified asacommand 
name or nothing if -type would not return file. If a command is hashed, -path 
prints the hashed value, not necessarily thefile that appears first in path. If the -all 
flag is used, type prints all of the places that contain an executable named name. This 
includes aliases and functions, if and only if the -path flag is not also used. T he table 
of hashed commands is not consulted when using -aii. type accepts -a, -t,and -pin 
placeof -aii, -type, and -path, respectively. An argument of - disablesoption 
checking for the rest of the arguments type returns True if any of the arguments are 
found, False if none are found. 

uiimit [-SHacdfmstpnuv [limit]] uiimit provides control over the resources available to theshell and to processes 

started by it, on systems that allow such control. The value of limit can be a number 
in the unit specified for the resource, or thevalue unlimited. T he h and s options 
specify that the hard or soft limit is set for the given resource. A hard limit cannot be 
increased once it is set; a soft limit may be increased up to the value of the hard 
limit. If neither h nor s isspecified, thecommand applies to the soft limit. If limit is 
omitted, the current value of the soft limit of the resource is printed, unless the h 
option is given. When more than one resource is specified, the limit name and unit 
is printed before thevalue Other options are interpreted asfollows 
-a All current limits are reported. 

-c Themaximum sizeof corefilescreated. 

-d Themaximum size of a process's data segment. 

-t Themaximum size of files created by the shell. 

-m Themaximum resident set size 

-s Themaximum stack size. 

-t Themaximum amount of cpu time in seconds 

-p The pipe size in 512-byte blocks (Thismay not beset.) 

-n Themaximum number of open file descriptors (M ost systems 

do notallow this value to beset, only displayed.) 

-u Themaximum numberof processes availableto a single user. 

-v Themaximum amount of virtual memory availableto the 

shell. 

An argument of - disablesoption checking for the rest of the arguments. If limit is 
given, it isthe new value of the specified resource (the -a option isdisplay only). If 
no option isgiven, then -f is assumed. Values are in 1024-byte increments except 
for -t, which is in seconds -p, which is in units of 512-byte blocks; and -nand -u, 




which are unsealed values The return status iso unless an illegal option Rencoun¬ 
tered, a non-numeric argument other than unlimited issupplied as limit, or an error 
occurswhilesettinganew limit. 

umask [-S] [mode ] Theuser file-creation mask isset to mode . If mode begins with a digit, it is interpreted 

as an octal number; otherwise, it is interpreted asa symbolic mode mask similar to 
that accepted by chmod(l). If mode is omitted, or ifthe-s option issupplied, the 
current value of the mask is printed. The-s option causes the mask to be printed in 
symbolic form; the default output is an octal number. An argument of - disables 
option checking for the rest of the arguments The return status iso if the mode was 
successfully changed or if no mode argument was supplied, and False otherwise, 
unaiias [-a] [name ...] Remove namesfrom the list of defined aliases. If -a issupplied, all aliasdefinitions 

are removed. The return value isTrue unless a supplied name is not a defined alias 
unset [-fv] [name ...] For each name remove the corresponding variable or, given the -f option, function. 

An argument of - disables option checking forthe rest of thearguments Note that 
path, ifs, ppid, psi, PS2, uid, and euid cannot be unset. If any of random, seconds, 
lineno, or histcmd are unset, they lose their special properties, even if they are 
subsequently reset. T he exit status isTrue unless a name does not exist or is non- 
unsettable. 

watt [n ] Wait for the specified process and return its termination status, n maybeaprocess 

ID or a job specification; if a job spec is given, all processes in that job's pipeline are 
waited for. If n is not given, all currently active child processes are waited for, and the 
return status is zero. If n specifies a nonexistent process or job, the return status is 
127.0 therwise the return status is the exit status of the last process or job waited 
for. 

INVOCATION 

A login shell is one whose first character of argument zero is a-, or one started with the-login flag. 

An interactive shell is one whose standard input and output are both connected to terminals (as determined by isatty(3)), or 
onestarted with the-i option, psi isset and includes i if bash is interactive allowing a shell script or a startup file to test this 
state. 


Login shells: 

On login (subject to the -noprofile option): 
if /etc/profile exists, source it. 
if "/.bash_profile exists, source it, 
else if '/.bash_login exists, source it, 
else if '/.profile exists, source it. 

if '/.bash_logout exists, source it. 

Non-login interactive shells: 

On startup (subject to the -norc and -refile options): 
if '/.bashre exists, source it. 

Non-interactive shells: 

On startup: 

if the environment variable ENV is non-null, expand 

it and source the file it names, as if the command 

if [ "$ENV" ]; then . $ENV; fi 

had been executed, but do not use PATH to search 

for the pathname. When not started in Posix mode, bash 

looks for BASH_ENV before ENV. 

If Bash is invoked assh, it tries to mimic the behavior of sh as closely as possible. For a login shell, it attempts to source only / 
etc/profiie and '/.profile, in that order. The -noprof iie option may still be used to disable this behavior. A shell invoked 
as sh does not attempt to source any other startup files 
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FI 


When bash isstarted in posix mode, as with the-posix command line option, it follows the PO SIX standard for startup files. 
In this mode theENv variable is expanded and that file sourced; no other startup files are read. 

SEE ALSO 

Bash Feature s Brian Fox and Chet Ramey 

TheGnu Readline Library, Brian Fox and Chet Ramey 

TheGnu History Library, Brian Fox and Chet Ramey 

A System 1/ Compatible Implementation of4.2BSD Job Control, David Lennert 

Portable Operating System Interface(POSIX) Part2: Shell and Utilities, IEEE 

sh( 1), ksh(l), csh(l), emacs(l), vi(l) readline(3) 

FILES 

/bin/bash 
/etc/profile 

/.inputrc 

AUTHORS 

Brian Fox (Free Software Foundation; primary author; bfox@ai.MiT.Edu), Chet Ramey (CaseWestern Reserve University; 
chet@ins.CWRU.Edu) 

COPYRIGHT 

Copyright© 1989,1991 by the Free Software Foundation, Inc. 

BUG REPORTS 

If you find a bug in bash, you should report it. But first, you should make sure that it really is a bug, and that it appears in 
the latest version of bash that you have 

Once you have determined that a bug actually exists, mail a bug report to bash-maintainers@prep.ai.M IT.Edu. If you have a 
fix, you are welcome to mail that as well! Suggestions and "philosophical" bug reports may be mailed to bug- 
bash@prep.ai.MIT.Edu Or posted to the Usenet newsgroup gnu.bash.bug. 

ALL bug reports should include the following: 

The version number of bash 

The hardware and operating system 

The compiler used to compile 

A description of the bug behavior 

A short script or "recipe^’ that exercises the bug 

Comments and bug reports concerning this manual page should be directed to chet@ins.cwru.edu. 

BUGS 

It's too big and too slow. 

There are some subtle differences between bash and traditional versionsof sh, mostly because of the posix specification. 
Aliases are confusing in some uses. 


The bash executable 

The systemwide initialization file executed for login shells 
The personal initialization file, executed for login shells 
Theindividual per- i n teracti ve- sh el I startup file 
Individual readline initialization file 


GNU, 9 March 1995 
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bdftopcf 

bdftopcf— Convert X font from Bitmap Distribution Format to PortableCompiled Format 

SYNOPSIS 

bdftopcf [ -pn ][-un ][-m ][-1 ][-M ][-L ][-t ][-i ][-0 out putf i I e ] fontfile.bdf 

DESCRIPTION 

bdftopcf is a font compiler for the x server and font server. Fonts in PortableCompiled Format can be read by any 

architecture, although thefile is structured to allow one particular architecture to read them directly without reformatting. 

This allows fast reading on the appropriate machine, but the files are still portable (but read more slowly) on other machines 

OPTIONS 

-pn sets the font glyph padding. Each glyph in thefontwill have each scanline padded in to a multiple 

of n bytes where n is 1,2,4, or 8. 

-un Sdtsthefont scanline unit. When the font bit order is different from the font byte order, the 

scanline unit n describes what unit of data (in bytes) are to be swapped; the unit i can bel, 2, or 4 
bytes. 

-m Sdts the font bit order to msb (most significant bit) first. Bits for each glyph will be placed in this 

order; that is the leftmost bit on the screen will be in the highest valued bitin each unit. 

-1 Sdts the font bit order to lsb (least significant bit) first. The leftmost biton the screen will be in the 

lowest valued bit in each unit. 

-m Sdts the font byte order to msb first. All multibyte data in thefile (metrics bitmaps and everything 

else) will be written most significant byte first. 

-l Sdtsthefont byte order to lsb first. All multibyte data in thefile (metrics bitmaps and everything 

else) will be written least significant byte first. 

-t W hen this option is specified, bdftopcf will convert fonts into terminal fonts when possible A 

terminal font haseach glyph image padded to the same size; the x server can usually render these 
types of fonts more quickly. 

-i This option inhibitsthe normal computation of ink metrics When a font has glyph images that do 

not fill the bitmap image (that is the "on" pixels don't extend to the edges of the metrics), bdftopcf 
computes the actual ink metrics and pi aces them in thepcF file; the-t option inhibits this behavior. 

-0 out put - f i 1 e-n ame By default bdftopcf writes the pcf file to standard output; this option gives the name of a fileto be 
used instead. 


SEE ALSO 

X(l) 

AUTHOR 

Keith Packard, M IT X Consortium 


X Version 11 Release6 


beforelight 

beforeiight- Screen saver 

SYNOPSIS 

beforeiight [ -tool ki topti on ... ] 
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DESCRIPTION 

The beforeiight program is a sample implementation of ascreen saver forx servers supporting the mit-screen-saver 
extension. 

AUTHORS 

Keith Packard (M IT X Consortium) 

X Version 11 Release 6 

biff 

biff- Be notified if mail arrives and who it is from 

SYNOPSIS 

biff [ny] 

DESCRIPTION 

biff informsthe system whether you want to be notified when mail arrives during the current terminal session. 

Options supported by biff: 
n Disables notification 

y Enables notification 

When mail notification isenabled, the header and first few lines of the message will be printed on your screen whenever mail 
arrives. A 

biff y 

command is often included in thefile .login or .profile to be executed at each login. 

B iff operates asynchronously. For synchronous notification use the mail variable of sh(l) or the mail variable of csh(l). 

SEE ALSO 

csh(l), mail(l), sh(l), comsat(8) 

HISTORY 

The biff command appeared in BSD 4.0. 

BSD 4,14 March 1991 

bioradtopgm 

bioradtopgm— Convert a Biorad confocal file into a portable graymap 

SYNOPSIS 

bioradtopgm [-image#] [i magedata] 

DESCRIPTION 

Readsa Biorad confocal fileasinput. Producesa portable graymap as output. If the resulting image is upside down, run it 
through pnmflip -tb. 



bitmap, bmtoa, atobm 




OPTIONS 

-image# A Biorad imagefile may contain more than oneimage With thisflag, you can specify which image to 

extract (only one at a time). Thefirst image in the file has number zero. If no image number is supplied, 
only information about the image size and the number of i mages in the input is printed out. N o output is 
produced. 

BUGS 

A Biorad image may be in word format. If PbmPius is not compiled with theBiGGRAYs flag, word files cannot be converted. See 

the makefile. 

SEE ALSO 

pgm(5), pnmflip(l) 

AUTHORS 

C opyright © 1993 by 0 liver T repte 

28Junel993 


bitmap, bmtoa, atobm 

bitmap, bmtoa, atobm- Bitmap editor and converter utilities for the X Window System 

SYNOPSIS 

bitmap [ -options ... ] [f i I cname Hbasename ] 
bmtoa [ -chars ...][fiI ename ] 

atobm [ -chars cc ][-name variabIe ][-xhot number ][-yhot number ][fi I ename ] 

DESCRIPTION 

The bitmap program is a rudimentary tool for creating or editing rectangular images made up of Is and Os. Bitmaps are used 
in x for defining clipping regions, cursor shapes, icon shapes, and tile and stipple patterns. 

The bmtoa and atobm filters convert bitmap files (file format) to and from ASCII strings They are most commonly used to 
quickly print out bitmaps and to generate versions for including in text. 

COMMAND-LINE OPTIONS 

Bitmap supports the standard X Toolkit command-line arguments see x(l). Thefollowing additional arguments are 
supported as well: 

-size Wl DTHxHEI GHT:' 

-sw di mensi on 
-sh di mensi on 
-gt di mensi on 

-grid, +grid 

-dashed, +dashed 
-stippled, +stippled 


Specifies size of the grid in squares 
Specifies the width of squares in pixels 
Specifies the height of squares in pixels. 

Grid tolerance If the square dimensionsfall below the specified value, grid will be 
automatically turned off. 

Turns on or off the grid lines 
T urns on or off the major axes 
T urns on or off dashing for the frame and grid lines. 

Turnson or off stippling of highlighted squares 
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-proportional, +proportional 


-dashes fiI ename 
-stipple fiIename 
-hi color 




bmtoa accepts the following option: 


atobm accepts the following options 


-name variable 




T urns proportional mode on or off. If proportional mode ison, square width is 
equal to square height. If proportional modeisoff, bitmap will use the smaller square 
dimension, if they were initially different. 

Specifies the bitmap to be used asa stipple for dashing. 

Specifies the bitmap to be used asa stipple for highlighting. 

Specifies the color used for highlighting. 

Specifi es the color used for the frame and grid lines 

Specifies the bitmap to be initially loaded into the program. If the file does not exist, 
bitmap will assume it is a new file. 

Specifies the basename to be used in the C code output file. If it is different than the 
basename in the working file, bitmap will change it when saving thefile. 


T his option specifies the pai r of characters to use in the string version of the bitmap. 
Thefirst character is used for 0 bits and the second character is used for 1 bits The 
default is to use dashes (-) for Os and number signs (#) for Is 


Thisoption specifies the pai r of characters to use when converting string bitmaps 
into arrays of numbers. T he first character represents a 0 bit and the second 
character represents a 1 bit. T he default is to use dashes (-) for Os and number signs 
(#) for Is. 

Thisoption specifies the variable name to be used when writing out the bitmap file 
The default is to use the basename of the filename command-line argument or leave 
it blank if the standard input is read. 

Thisoption specifies the X coordinate of the hot spot. Only positive values are 
allowed. By default, no hotspot information is included. 

This option specifies the Y coordinate of the hot spot. 0 nly positive values are 
allowed. By default, no hotspot information is included. 


USAGE 

bitmap displays grid in which each square represents a single bitin the picture being edited. Actual size of the bitmap image 
as it would appear normally and inverted, can be obtained by pressing M eta-l. You are free to move the image pop-up out of 
the way to continue editing. Pressing the left mouse button in the pop-up window or M eta-l again will remove the real size 
bitmap image. 

If the bitmap is to be used for defining a cursor, one of the squares in the image may be designated as the hot spot. This 
determine where the cursor is actually pointing. For cursors with sharp tips (such as arrows or fingers), this is usually at the 
end of thetip; for symmetric cursors (such ascrosseor bulls-eye), this is usually at the center. 

Bitmaps are stored as small C code fragments suitable for including in applications. They provide an array of bits as well as 
symbolic constants giving the width, height, and hot spot (if specified) that may be used in creating cursore, icons, and tile. 

EDITING 

To edit a bitmap image simply click on one of the buttons with drawing commands (Point, Curve, Line Rectangle, and so 
on) and move the pointer into the bitmap grid window. Press one of the buttons on your mouse and the appropriate action 
will take place. You can either set, clear, or invert the grid squares. Setting a grid square corresponds to setting a bit in the 
bitmap image to 1. Clearing a grid square corresponds to setting a bit in the bitmap image to 0. Inverting a grid square 
corresponds to changing a bit in the bitmap image from a to i or i to 0, depending what its previous state was The default 
behavior of mouse buttons isasfollows: 
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MouseButtonl Set 
MouseButton2 Invert 
MouseButton3 Clear 
MouseButton4 Clear 
MouseButton5 Clear 

This default behavior can be changed by setting the button function resources Here is an example: 

bitmap*button1Function: Set 
bitmap*button2Function: Clear 
bitmap*button3Function: Invert 


The button function applies to all drawing commands including copying, moving and pasting, flood filling, and setting the 

hot spot. 

DRAWING COMMANDS 

H ere is the list of drawing commands accessible through the buttons at the left side of the application's window. Some 

commandscan be aborted by pressing A inside thebitmap window, allowing the user to select different guiding points where 

applicable. 

Clear This command clears all bitsin thebitmap image. Thegrid squareswill besettothe 

background color. PressingC inside the bitmap window has the same effect. 

Set This command sets all bitsin thebitmap image. Thegrid squareswill beset to the 

foreground color. Pressing S inside the bitmap window has the same effect. 

Invert This command inverts all bitsin thebitmap image Thegrid squareswill beinverted 

appropriately. Pressing I inside the bitmap window has the same effect. 

Mark This command is used to mark an area of the grid by dragging out a rectangular 

shape in the highlighting color. After the area is marked, it can be operated on by a 
number of commands (see Up, Down, Left, Right, Rotate Flip, Cut, and soon). 

0 nly one marked area can be present at any time If you attempt to mark another 
area, the old mark will vanish. The same effect can be achieved by pressing Shift- 
M ouseButtonl and dragging out a rectangle in thegrid window. Pressing Shift- 
M ouseButton2 will mark the entire grid area. 

Unmark This command will cause the marked areato vanish.Thesameeffect can be 

achieved by pressing Shift-M ouseButton3. 

Copy This command is used to copy an area of the grid from one location to another. If 

there isno marked grid area displayed, Copy behavesjust like M ark. 0 nee there is a 
marked grid area displayed in the highlighting color, this command has two 
alternative behaviors If you click a mouse button inside the marked area, you will be 
able to drag the rectangle that represents the marked areato the desired location. 
After you release the mouse button, the area will be copied. If you click outside the 
marked area, Copy will assume that you wish to mark a different region of the 
bitmap image, thus it will behave like M ark again. 

Move This command is used to move an area of thegrid from one location to another. Its 

behavior resembles the behavior of Copy command, except that the marked area will 
be moved instead of copied. 

Flip Horizontally This command will flip thebitmap image with respect to the horizontal axes. If a 

marked area of thegrid is highlighted, it will operate only inside the marked area. 
Pressing H inside the bitmap window has the same effect. 

Up This command moves the bitmap image one pixel up. If amarked area of the grid is 

highlighted, it will operate only inside the marked area. Pressing UpA mow inside the 
bitmap window has the same effect. 
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Flip Vertically 

Left 

Fold 

Right 

Rotate Left 

Down 

Rotate Right 

Point 

Curve 

Line 

Rectangle 

Filled Rectangle 
Circle 

Filled Circle 
Flood Fill 


This command will flip the bitmap image with respect to the vertical axes If a 
marked area of thegrid is highlighted, it will operate only inside the marked area. 
PressingV inside the bitmap window has the same effect. 

This command moves the bitmap image one pixel to the left. If a marked area of the 
grid is highlighted, it will operate only inside the marked area. Pressing LeftArrow 
inside the bitmap window has the same effect. 

This command will fold the bitmap image so that the opposite corners become 
adjacent. This is useful when creating bitmap images for tiling. Pressing F inside the 
bitmap window has the same effect. 

This command moves the bitmap image one pixel to the right. If a marked area of 
thegrid is highlighted, it will operate only inside the marked area. Pressing the right 
arrow inside the bitmap window has the same effect. 

This command rotates the bitmap image 90 degrees to the left (counterclockwise) 

If a marked area of thegrid is highlighted, it will operate only inside the marked 
area. Pressing L inside the bitmap window has the same effect. 

This command moves the bitmap image one pixel down. If a marked area of thegrid 
is highlighted, it will operate only inside the marked area. Pressing the down arrow 
inside the bitmap window has the same effect. 

Thiscommand rotates the bitmap image 90 degrees to the right (clockwise.) If a 
marked area of thegrid is highlighted, it will operate only inside the marked area. 
Pressing R inside the bitmap window hasthesameeffect. 

Thiscommand will change the grid squares underneath the mouse pointer if a 
mouse button is being pressed down. If you drag the mouse button continuously, 
the line may not be continuous, depending on the speed of your system and 
frequency of mouse motion events 

Thiscommand will change the grid squares underneath the mouse pointer if a 
mouse button is being pressed down. If you drag the mouse button continuously, it 
will make sure that the line iscontinuous If your system isslow or bitmap receives 
very few mouse motion events, it might behavequite strangely. 

Thiscommand will change the grid squares in a line between two squares. 0 nee you 
press a mouse button in thegrid window, bitmap will highlight the line from the 
square where the mouse button was initially pressed to the square where the mouse 
pointer is located. By releasing the mouse button, you will cause the change to take 
effect, and the highlighted line will disappear. 

Thiscommand will change the grid squares in a rectangle between two squares. 

Once you press a mouse button in thegrid window, bitmap will highlight the 
rectangle from the square where the mouse button was initially pressed to the square 
where the mouse pointer islocated. By releasing the mouse button you will cause the 
change to take effect, and the highlighted rectangle will disappear. 

Thiscommand is identical to Rectangle except at the end the rectangle will be filled 
rather than outlined. 

Thiscommand will change the grid squares in a circle between two squares. Once 
you press a mouse button in thegrid window, bitmap will highlight the circle from 
the square where the mouse button was initially pressed to the square where the 
mouse pointer islocated. By releasing the mouse button you will cause the change to 
take effect, and the highlighted circle will disappear. 

Thiscommand is identical to Circle except at the end the circle will be filled rather 
than outlined. 

Thiscommand will flood fill the connected area underneath the mouse pointer 
when you click on the desired square Diagonally adjacent squares are not considered 
to be connected. 
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Set H ot Spot This command designates one square in the grid as the hot spot if this bitmap image 

is to be used for defining a cursor. Pressing a mouse button in the desired square will 
cause a diamond shape to be displayed. 

Clear H ot Spot This command removes any designated hot spot from the bitmap image. 

Undo This command will undo the last executed command. It has depth one that is, 

pressing U ndo after U ndo will undo itself. 

FILE MENU 

The File menu commands can be accessed by pressing the File button and selecting the appropriate menu entry, or by 
pressing the C trl key with another key. T hese commands deal with files and global bitmap parameters, such as size, 
basename, filename, and so forth. 

New This command will clear the editing area and prompt for the name of the new file to 

be edited. It will not load in the new file 

Load Thiscommand isused to load a new bitmap file into the bitmap editor. Ifthe 

current image has not been saved, user will be asked whether to save or ignore the 
changes The editor can editonlyonefileatatime If you need interactive editing, 
run a number of editors and use the cut and paste mechanism as described later in 
thissection. (See"Cut and Paste") 

Insert Thiscommand isused to insert a bitmap file into the image being currently edited. 

After being prompted for the filename click inside the grid window and drag the 
outlined rectangle to the location where you want to insert the new file. 

Save Thiscommand will savethebitmap image. It will not prompt for the filename 

unless it is said to be <none>. If you leave thefilename undesignated or - , the output 
will be piped to stdout. 

Save As Thiscommand will save the bitmap image after prompting for a new filename. It 

should be used if you want to change thefilename. 

Resize Thiscommand isused to resize the editing area to the new number of pixels The 

size should be entered in the widthl height format. The information in theimage 
being edited will not be lost unless the new size is smaller that the current image size 
The editor was not designed to edit huge files 

Rescale Thiscommand isused to rescale the editing area to the new width and height. The 

size should be entered in the widthl heightformat. It will not do antialiasing and 
information will be lost if you rescale to the smaller sizes. Feel free to add you own 
algorithmsfor better rescaling. 

Filename Thiscommand isused to change the filename without changing the basename nor 

saving thefile. If you specify - for a filename, the output will be piped to stdout. 
Basename Thiscommand isused to change the basename if a different one from the specified 

filename isdesi red. 

Quit Thiscommand will terminate the bitmap application. If the file was not saved, user 

will be prompted and asked whether to save the image or not. Quit is preferred over 
killing the process 

EDIT MENU 

The Edit menu commands can be accessed by pressing the Edit button and selecting the appropriate menu entry, or by 
pressing M eta key with another key. These commands deal with editing facilities such as grid, axes, zooming, cut and paste, 
and so on. 

Thiscommand will display the image being edited and its inverse in its actual size in 
a separate window. The window can be moved away to continue with editing. 

Pressing the left mouse button in the image window will cause it to disappear from 
the screen. 


lage 
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Grid 

Dashed 

Axes 

Stippled 

Proportional 

Zoom 

Cut 

Copy 

Paste 


This command controls the grid in the editing area. If the grid spacing is below the 
value specified by gridToierance resource (8 by default), the grid will be automati¬ 
cally turned off. Itcan be enforced by explicitly activating thiscommand. 

This command controls the stipple for drawing the grid lines The stipple specified 
by dashes resource can be turned on or off by activating this command. 

This command controls the highlighting of the main axes of the image being edited. 
The actual lines are not part of the image. They are provided to aid user when 
constructing symmetrical images or whenever having the main axes highlighted 
helps your editing. 

Thiscommand controls the stippling of the highlighted areas of the bitmap image. 
The stipple specified by stipple resource can be turned on or off by activating this 
command. 

Thiscommand controls the proportional mode If the proportional modeison, 
width and height of all image squares are forced to be equal, regardless of the 
proportions of the bitmap window. 

Thiscommand controls the zoom mode If there is a marked area of the image 
already displayed, bitmap will automatically zoom into it. 0 therwise, the user will 
have to highlight an area to be edited in the zoom mode and bitmap will automati¬ 
cally switch into it. You can use all the editing commands and other utilities in the 
zoom mode. W hen you zoom out, undo command will undo the whole zoom 
session. 

This commands cuts the contents of the highlighted image area into the internal cut 
and paste buffer. 

Thiscommand copies the contents of the highlighted image area into the internal 
cut and paste buffer. 

Thiscommand will check if there are any other bitmap applications with a 
highlighted image area, or if there is something in the internal cut and paste buffer 
and copy it to the image T o place the copied image, click in theediting window and 
drag the outlined image to the position where you wantto placei, and then release 
the button. 


CUT AND PASTE 

Bitmap supports two cut and paste mechanisms; the internal cut and paste and the global X selection cut and paste. T he 
internal cut and paste is used when executing copy and movedrawing commands and also cut and copy commands from the 
Edit menu. The global X selection cut and paste is used whenever there isa highlighted area of a bitmap image displayed 
anywhere on the screen. To copy a part of image from another bitmap editor, simply highlight the desired area by using the 
M ark command or pressing the shift key and dragging the area with the left mouse button. W hen the selected area becomes 
highlighted, any other applications (such as xterm) that use primary selection will discard their selection values and 
unhighlight the appropriate information. Now, use the Paste command from the Edit menu or control mouse button to 
copy the selected part of image into another (or the same) bitmap application. If you attempt to do this without a visible 
highlighted image area, the bitmap wi 11 fal I back to the internal cut and paste buffer and paste whatever was stored there at 
the moment. 


WIDGETS 

Following is the widget structure of the bitmap application. The widget class name is given first, followed by the widgdt 
instance name. All widgets except the bitmap widget are from the standard Athena widget set. 

Bitmap bitmap 
TransientShell image 

Label normallmage 
Label invertedlmage 
TransientShell input 
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Dialog dialog 

Command cancel 
TransientShell error 
Dialog dialog 

Command retry 
TransientShell qsave 
Dialog dialog 
Command yes 
Command no 
Command cancel 
Paned parent 
Form formy 

MenuButton fileButton 
SimpleMenu fileMenu 
SmeBSB new 
SmeBSB load 


SmeBSB saveAs 
SmeBSB resize 
SmeBSB rescale 
SmeBSB filename 
SmeBSB basename 

SmeBSB quit 
MenuButton editButton 
SimpleMenu editMenu 
SmeBSB image 
SmeBSB grid 
SmeBSB dashed 
SmeBSB axes 
SmeBSB stippled 
SmeBSB proportional 
SmeBSB zoom 
SmeLine line 
SmeBSB cut 
SmeBSB copy 
SmeBSB paste 

Pane pane 
Bitmap bitmap 

Command clear 
Command set 

Toggle mark 
Command unmark 
Toggle copy 

Command flipHoriz 
Command up 
Command fLipVert 
Command left 

Command right 
Command rotateLeft 
Command down 


Command rotateRight 
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Toggle point 

Toggle rectangle 
Toggle filledRectangle 
Toggle circle 
Toggle filledCircle 
Toggle floodFill 
Toggle setHotSpot 
Command clearHotSpot 
Command undo 

COLORS 

If you would like bitmap to be viewable in color, include thefollowing in the#ifdef color section of thefileyou read with 

•customization: -color 

This will cause bitmap to pick up the colors in the app-defaults color customization file 

<XRoot>/lib/X11/app-defaults/Bitmap-color 

where <xRoot> refers to the root of the X11 install tree. 

BITMAP WIDGET 

Bitmap widget is a standalone widget for editing raster images It is not designed to edit large images, although it may be 
used in that purpose as well. Itcan be freely incorporated with other applications and used asastandard editing tool. The 
following are the resources provided by the bitmap widget: 

Headerfile Bitmap, h 

Class bitmapWidgetClass 

C lass N ame Bitmap 

Superclass Bitmap 

All the Simple Widget resources plus... 


Name 

Class 

Type 

Default Value 

foreground 

Foreground 

Pixel 

XtD efaultForeground 

highlight 

FI ighlight 

Pixel 

XtD efaultForeground 

framing 

Framing 

Pixel 

XtD efaultForeground 

gridT olerance 

GridT olerance 

Dimension 

8 

size 

Size 

String 

32x32 

dashed 

Dashed 

Boolean 

True 

grid 

Grid 

Boolean 

True 

stippled 

Stippled 

Boolean 

True 

proportional 

Proportional 

Boolean 

True 

axes 

Axes 

Boolean 

False 

squareWidth 

SquareWidth 

Dimension 

16 

squareH eight 

SquareH eight 

Dimension 

16 

margin 

M argin 

Dimension 

16 

xH ot 

X H ot 

Position 

NotSet(-l) 

yH ot 

YH ot 

Position 

NotSet(-l) 

buttonlFunction 

ButtonlFunction 

DrawingFunction 

Set 
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Name 

button2Function 

button3Function 

button4Function 

button5Function 

filename 

basename 


Class 

Button2Function 

Button3Function 

Button4Function 

Button5Function 

Filename 

Basename 


AUTHOR 

Davor M atic (M IT X Consortium) 


Type Default Value 

DrawingFunction Invert 

DrawingFunction Clear 

DrawingFunction Invert 

DrawingFunction Invert 

String Nonet"") 

String Nonet"") 


X Version 11 Release6 


bmptoppm 

bmptoppm- Convert a BM P file into a portable pixmap 

SYNOPSIS 

bmptoppm [bmpfile] 

DESCRIPTION 

bmptoppm reads a M icrosoft W i ndows or 0 S/2 B M P file as input and produces a portable pixmap as output. 

SEE ALSO 

ppmtobmp(l), ppm(5) 

AUTHOR 

Copyright © 1992 by D avid W. Sanderson 

26 October 1992 


brushtopbm 

brushtopbm- C onvert a doodle brush file into a portable bitmap 

SYNOPSIS 

brushtopbm [brushfiI e ] 

DESCRIPTION 

brushtopbm reads a Xerox doodle brush file as input and produces a portable bitmap as output. 
N otethat there is currently no pbmtobrush tool. 

SEE ALSO 

pbm(5) 

AUTHOR 

Copyright © 1988 byjef Poskanzer 


28 August 1988 
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cai-Displays a calendar 

SYNOPSIS 

cal My] [month [year]] 

DESCRIPTION 

cai displays a si mple calendar. I f arguments are not specified, the current month is displayed. The options are as follows 
-j Displayjulian dates (days one-based, numbered fromJanuary 1) 

-y Display a calendar for the current year 

A single parameter specifies the year (1-9999) to be displayed; note the year must be fully specified: 


will not display a calendar for 1989. T wo parameters denote the month (1-12) and year. If no parameters are specified, the 
current month's calendar is displayed. 

A year starts on Jan 1. 

The Gregorian Reformation is assumed to have occurred in 1752 on the 3rd of September. By this time, most countries had 
recognized the reformation (although a few did not recognize it until the early 1900s) Ten days following that date were 
eliminated by the reformation, so the calendar for that month is a bit unusual. 

HISTORY 

A cai command appeared in version 6 AT&T UNIX 

6Junel993 


cat 

cat- Concatenate files and print on the standard output 

SYNOPSIS 

cat [-benstuvAET] [ — number] [—number-nonblank] [-squeeze-blank] 
[-show-nonprinting] [-show-ends] [-show-tabs] [-show-all] 


[ -help] [-version] [file...] 


DESCRIPTION 

This manual page documents the GN U version of cat. cat writes the contents of each given file, or the standard input if 
none are given or when a file named - is given, to the standard output. 


OPTIONS 

-b, —number-nonblank 


-n, —number 

-s, -squeeze-blank 


Number all nonblank output lines, starting with 1. 
Equivalentto -vE. 

N umber all output lines, starting with 1. 

Replace multi pie adjacent blank lines with a single blank line. 
Equivalentto -vt. 

Ignored; for U NIX compatibility. 




-A, -show-all 
-E, -show-ends 

— version 


Display control characters except for lfd and tab using * notation and precede characters that 
have the high bit set with m-. 

Equivalents -vet. 

Display a $ after the end of each line 
D isplay tab characters as *i. 

Print a usage message and exit with a nonzero status. 

Print version information on standard output then exit. 

GNU Text Utilities 
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chatti— C hangefile attributes on a Linux second extended file system 

SYNOPSIS 

chattr [ -RV ][-v version ] [ mode ] files... 

DESCRIPTION 

chattr changes the files attributes on an second extended filesystem. The format of a symbolic modeis+-=[Sacdisu]. 

T he operator + causes the selected attributes to be added to the existing attributes of the fi les; - causes them to be removed; 
and = causes them to be the only attributes that the files have. The letters sacdisu select the new attributesfor the files: 
synchronous updates (s), append only (a), compressed (jc), immutable(i), nodump (d), securedeletion (s), and undeletable 
(u). 

OPTIONS 

-r Recursively change attributes of directories and theircontents 

-v Verbosely describe changed attributes. 

-v version Set the file's version. 

ATTRIBUTES 

A file with the a attribute set can only be open in append mode for writing. 

A file with thee attribute set is automatically compressed on thedisk by the kernel. A read from thisfile returns 
uncompressed data. A write to thisfile compresses data before storing them on thedisk. 

A file with the d attribute set is not candidate for backup when the dump(8) program isrun. 

A file with the i attribute cannot be modified: it cannot be deleted or renamed, no link can be created to thisfile and no data 
can be written to thefile. 0 nly the superuser can set or clear this attribute. 

W hen a file with the s attribute set is deleted, its blocks are zeroed and written back to the disk. 

W hen a file with the u attribute set is modified, the changes are written synchronously on the disk; this is equivalent to the 
syn' mount option applied to a subset of the files. 

When a file with theu attribute set is deleted, its contents is saved. This allows the user to ask for its undeletion. 

AUTHOR 

chattr has been written by Remy Card, <card@masi.ibp.fr>, the developer and maintainer oftheext2 fs. 

BUG SAND LIMITATIONS 

As of ext2 f s 0.5a, the c and u attributes are not honored by the kernel code 
These attributes will beimplemented in afutureext2 fs version. 
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AVAILABILITY 

chattr is avail able for anonymous ftp from ftp.ibp.fr and tsx-i 


/pub/linux/packages/ext2fs. 


SEE ALSO 

lsattr(l) 


Verson 0.5b, N ovember 1994 


chfn 

chfn— C hange your finger information 

SYNOPSIS 

chfn [ -f full-name ][-o o f f i c e][-p office-phone ] [ -h home-phone ] [ -u ] [ -v ] 
[username ] 


DESCRIPTION 

chfn is used to change your finger information. This information is stored in the/etc/passwd file and isdisplayed by the 
finger program. The Linux finger command will display four pieces of information that can be changed by chfn: your real 
name your work room and phone, and your home phone. 

COMMAND LINE 

Any of the four pieces of information can be specified on the command line If no information isgiven on the command 
line chfn enters interactive mode 

INTERACTIVE MODE 

In interactive mode chfn will prompt for each field. At a prompt, you can enter the new information, or just press return to 
leave the field unchanged. Enter the keyword none to makethefield blank. 

OPTIONS 

-f, -full-name 
-o, -office 
-p, -office-phone 
-h, -home-phone 
-u, -help 

SEE ALSO 

finger(l), passwd(5) 

AUTHOR 

Salvatore V alente (<svalente@mit. edu>) 


Specify your real name. 

Specify your office room number. 
Specify your office phone number. 
Specify your home phone number. 
Print a usage message and exit. 
Print version information and exit. 


chfn, October 13 1994 
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chgrp 

chgrp- Change the group ownership of files 

SYNOPSIS 

chgrp [-Rcfv] [ — recursive] [ — changes] [-silent] [—quiet] [—verbose] [—help] 

[ — version] group file... 

DESCRIPTION 

This manual page documents the GN U version of chgrp. chgrp changes the group ownership of each given file to thenamed 
group, which can be either a group name or a numeric group ID. 

OPTIONS 

-c, —changes 

-R, —recursive 

— version 

chkdupexe 

chkdupexe— Find duplicate executables 

SYNOPSIS 

chkdupexe 

DESCRIPTION 

chkdupexe will scan many standard directories that hold executable, and report duplicates 

AUTHOR 

Nicolai Langfddt 

BUGS 

RequiresGN U is(l). 

Search paths that point to the same directory will cause many bogus duplicates to be found. You might want to edit the 
script to eliminate some paths that are equivalent on your machine 

11 March 1995 


Verbosely describe only files whose ownership actually changes. 

D o not print error messages about files whose ownership cannot be changed. 

Verbosely describe ownership changes 

Recursively change ownership of directories and their contents. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output, then exit successfully. 

GNU File Utilities 


chmod 

chmod- C hange the access permissions of files 

SYNOPSIS 


chmod [-Rcfv] [-recursive] [-changes] [-silent] [-quiet] [-verbose] [-help] 
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DESCRIPTION 

This manual page documents the GN U version of chmod. chmod changes the permissions of each given file according to mode, 
which can be either a symbolic representation of changes to make or an octal number representing the bit pattern for the 
new permissions 

Theformat of a symbolic mode is [ugoa... ] [ [+■=] [rwxxstugo M ultiple symbolic operationscan be given, 
separated by commas. 

A combination of the letters ugoa controls which users' access to thefile will be changed: the user who owns it (u), other users 
in thefile'sgroup (g), other users not in the file's group (o), or all users (a). I f none of these are given, the effect is as if a were 
given, but bits that are set in the umask are not affected. 

T he operator + causes the permissions selected to be added to the existing permissions of each file; - causes them to be 
removed; and = causes them to be the only permissions that the file has. 

The letters rwxxstugo select the new permissions for theaffected users: read (r), write (w), execute (or access for directories) 

(x), execute only if thefile is a directory or already has execute permission for some user (x), set user or group ID on 
execution (s), save program text on swap de/ice (t), thepermissionsthatthe user who owns the file currently has for it (u), 
the permissionsthat other users in thefile'sgroup have for it (g), and the permissions that other users not in thefile'sgroup 
have for it (o). 

A numeric mode is from one to four octal digits (0-7), derived by adding up the bits with values 4, 2, and 1. Any omitted 
digits are assumed to be leading zeros. Thefirst digit selects theset user ID (4) and set group ID (2) and save text image (1 ) 
attributes The second digit selects permissionsfor the user who owns the file: read (4), write (2), and execute (1); the third 
selects permissionsfor other users in thefile'sgroup, with the same values and the fourth for other users not in thefile's 
group, with the same values 

chmod never changes the permissions of symbolic links; the chmod system call cannot change their permissions. This is not a 
problem since the permissions of symbolic links are never used. H owever, for each symbolic link listed on the command line, 
chmod changes the permissions of the pointed-to file. In contrast, chmod ignores symbolic links encountered during recursive 
directory traversals 

OPTIONS 

-c, -changes 

-v, -verbose 
-R, -recursive 
-help 

GNU File Utilities 


Verbosely describe only files whose permissions actually change 

D 0 not print error messages about files whose permissions cannot be changed. 

Verbosely describe changed permissions 

Recursively change permissions of directories and their contents. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output, then exit successfully. 


chown 

chown— C hange the user and group ownership of files 

SYNOPSIS 

chown [-Rcfv] [ — recursive] [-changes] [-help] [—version] [—silent] [-quiet] 
[-verbose] [user ][:.][group] file... 



chsh 


in 

DESCRIPTION 

This manual page documents the GN U version of chown. chown changes the user and/or group ownership of each given file, 
according to its first nonoption argument, which is interpreted as follows If only a username (or numeric user ID) is given, 
that user is made the owner of each given file and the files' group is not changed. If the username isfollowed by a colon or 
dot and a group name (or numeric group ID), with no spaces between them, the group ownership of thefiles is changed as 
well. If a colon or dot but no group name follows the username that user is made the owner of the files and the group of the 
files is changed to that user's login group. I f the colon or dot and group are given, but the username is omitted, only the 
group of thefiles ischanged; in thiscase chown performs the same function aschgrp. 

OPTIONS 

Verbosely describe only files whose ownership actually changes. 

D o not print error messages about files whose ownership cannot be changed. 

Verbosely describe ownership changes 
Recursively change ownership of directories and their contents. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output then exit successfully. 

GNU File Utilities 

chsh 

chsh— Change your login shell 

SYNOPSIS 

chsh [ -s shell 1 [ -1 ] [ -u ] [ -v ] [ username ] 

DESCRIPTION 

chsh is used to change your login shell. If a shell is not given on the command line, chsh prompts for one 

VALID SHELLS 

chsh will accept the full pathname of any executable file on the system. However, it will issue a warning if the shell is not 
listed in the /etc/sheiis file 

OPTIONS 

-s, -shell Specify your login shell. 

-l, -list-sheiis Print the list of shells listed in /etc/sheiis and exit. 

-u,-help Print a usage message and exit. 

-v, -version Print version information and exit. 

SEE ALSO 

login(l), passwd(5), shells(5) 

AUTHOR 

Salvatore V alente (<svalente@mit. edu>) 

chsh, 13 October 1994 
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ci 

ci— Check in RCS revisions 

SYNOPSIS 

ci [options] file ... 

DESCRIPTION 

ci stores new revisions into RCSfiles. Each pathname matching an RCS suffix is taken to bean RCSfile All others are 
assumed to be working files containing new revisions, ci deposits the contents of each working file into the corresponding 
RCSfile. If only a working file is given, ci tries to find the corresponding RCS file in an RCS subdirectory and then in the 
working file's directory. (For more details, see "File Naming," later in this manual page.) 

Forcito work, the caller's login must be on the access list, unless the access list isempty or the caller is thesuperuser or the 
owner of the file To append a new revision to an existing branch, the tip revision on that branch must be locked by the 
caller. Otherwise, only anew branch can be created. This restriction is not enforced for the owner of the file if non-strict 
locking is used; seercs(l). A lock held by someone else can be broken with the res command. 

Unless the-f option is given, ci checks whether the revision to be deposited differs from the preceding one If not, instead of 
creating a new revision ci reverts to the preceding one. To revert, ordinary ci removes the working file and any lock; ci -I 
keeps and ci -u removes any lock, and then they both generate a new working file much as if co -lor co -u had been applied 
to the preceding revision. When reverting, any-n and -s options apply to the preceding revision. 

For each revision deposited, ci prompts for a log message. T he log message should summarize the change and must be 
terminated by end-of-fileor by a line containing . by itself. If several files are checked in, ci asks whether to reuse the 
previ ous log message. I f the standard input is not a termi nal, ci suppresses the prompt and uses the same log message for al I 
files (Seealso -n.) 

If the RC S file does not exist, ci creates it and deposits the contents of the working file as the initial revision (default 
number: i . 1 ). T he access list isinitialized to empty. Instead of the log message, ci requests descriptive text (See -t.) 

The number rev of the deposited revision can be given by any of the options -f, -i, - 1 , - j, -k, - 1 , -m, -q, -r, or -u. rev can be 
symbolic, numeric, or mixed. Symbolic names in rev must already be defined; see the -n and -Noptionsfor assigning names 
during checkin. If rev is $, ci determines the revision number from keyword values in the working file 
If rev begins with a period, then the default branch (normally the trunk) is prepended to it. If rev isa branch number 
followed by a period, then the latest revision on that branch is used. 

If rev isa revision number, it must be higher than the latest one on the branch to which rev belongs, or must start a new 
branch. 

If rev isa branch rather than a revision number, thenav revision is appended to that branch. The level number is obtained 
by incrementing the tip revision number of that branch. If rev indicates a nonexistent branch, that branch is created with the 
initial revision numbered rev.i. 

If rev is omitted, ci tries to derive the new revision number from the caller's last lock. If the caller has locked the tip revision 
of a branch, the new revision is appended to that branch. The new revision number is obtained by incrementing the tip 
revision number. If the caller locked a nontip revision, a new branch isstarted at that revision by incrementing the highest 
branch number at that revision. The default initial branch and level numbers are 1. 

If rev isomitted and the caller has no lock, but owns the file and locking is not set to strict, then the revision is appended to 
the default branch. (N ormally the trunk; see the -b option of rcs(l).) 

Exception: On thetrunk, revisionscan be appended to theend, but not inserted. 





OPTIONS 


-rrev Check in revision rev. 

-r The bare -r option (without any revision) hasan unusual meaning in ci. With other RCS 

commands, a bare -r option specifies the most recent revision on the default branch, but with ci, a 
bare -r option reestablishes the default behavior of releasing a lock and removing the working file, 
and is used to override any default -1 or -u options established by shell aliases or scripts 
-l [rev] Works like -r, except it performs an additional co -1 for the deposited revision. Thus, the 

deposited revision is immediately checked out again and locked. This is useful for saving a revision 
although one wants to continue editing it after the checkin. 

-u [rev ] Works like -1, except that the deposited revision is not locked. This lets one read the working file 

immediately after checkin. 

The-i, bare -r, and -u optionsare mutually exclusive and silently override each other. For example, ci -u -r isequi valent 
to ci -r because bare -r overrides -u. 

-f [rev] Forces a deposit; the new revision isdeposited even it is not different from the preceding one. 

-k[rev ] Searches the working file for keyword values to determine its revision number, creation date state 

and author-see co(l)- and assigns these values to the deposited revision, rather than computing 
them locally. It also generates a default login message noting the login of the caller and the actual 
checkin date. This option is useful for software distribution. A revision that is sent to several sites 
should be checked in with the -k option at these sites to preserve the original number, date author, 
and state. The extracted keyword values and the default log message can be overridden with the 
options -d, -m, -s, -w, and any option that carries a revision number. 

-q [rev] Quiet mode; diagnostic output is not printed. A revision that is not different from the preceding 

one is not deposited, unless-f isgiven. 

- i [ r e v ] Initial checkin; report an error if the RCS file already exists. Thisavoids race conditions in certain 

applications. 

-j[rev] Just check in and do not initialize; report an error if the RCS file does not already exist. 

-i [rev] Interactive mode; the user is prompted and questioned even if the standard input is not a terminal, 

-d [date ] Uses date for the checkin date and time. The date is specified in free format as explained in co(l). 

This is useful for lying about the checkin date, and for-k if no date is available If date is empty, 
the working file’stime of last modification isused. 

-M[rev ] Set the modification time on any new working file to be the date of the retrieved revision. For 

example, ci -d -m -u t does not alter f’s modification time, even if f's contents change due to 
keyword substitution. U sethisoption with care; it can confuse make(l). 

-mmsg U ses the string ms g asthelogmessageforall revisions checked in. By convention, log messagesthat 

start with # are comments and are ignored by programs like GNU emacs's vc package Also, log 
messagesthat start with ciumpname (followed by whitespace) aremeantto be clumped together if 
possible even if they are associated with different files; the ciumpname label isused only for 
clumping, and is not considered to be part of the log message itself. 

-nname Assigns the symbolic name to the number of the checked-in revision, ci prints an error message if 

that name is already assigned to another number. 

-Nna me Same as -n, except that it overridesa previousassignment of name. 

-sstate Sets the state of the checked-in revision to the identifier state. The default state is Exp. 

-tf i i e W rites descriptive text from the contents of the named file into the RC S file deleting the existing 

text. The file cannot begin with -. 

-t-stri ng Write descriptive text from thestring into theRCS file deleting the existing text. 

The-t option, in both its forms, has effect only during an initial checkin; it issilently ignored otherwise. 

Duringthe initial checkin, if-t is not given, ciobtainsthe text from standard input, terminated byend-of-fileorbyaline 
containing a dot {.) by itself. The user is prompted for the text if interaction is possible see-i. 
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FI 

For backwardscompatibility with older versions of RCS, a bare-t option is ignored. 

-t Set the RCS file’s modification time to the new revision's time if theformer precedes the latter and 

there is a new revision; preserve the RCS file's modification time otherwise. If you have locked a 
revision, ci usually updates the RCS file's modification time to the current time because the lock is 
stored in the RC S file and removing the lock requires changing the RC S file. This can create an 
RC S file newer than the working file in one of two ways first, ci -m can create a working file with 
a date before the current time; second, when reverting to the previous revision the RC S file can 
change while the working file remains unchanged. These two cases can cause excessive 
recompilation caused by amake(l) dependency of the working file on the RCS file The -t option 
inhibits this recompilation by lying about the RC S file’sdate. U sethisoption with care it can 
suppress recompilation even when acheckin of one working file should affect another working file 
associated with the same RCS file. For example suppose the RC S file's time is 01:00, the (changed) 
working file's time is 02:00, some other copy of the working file has a time of 03:00, and the 
current time is 04:00. Then ci-d -T setsthe RCS file's time to 02:00 instead of the usual 04:00; 
this causes make(l) to think (incorrectly) that the other copy is newer than the RC S file 
-wi ogi n Uses login for the author field of the deposited revision. Useful for lying about the author, and for 

-k if no author is available 

-v Print RCS's version number. 

-vn Emulate RCS version n. See co(l) for details 

-xsuff i xes Specifies the suffixes for RCS files. A nonempty suffix matches any pathname ending in the suffi x. 

An empty suffix matches any pathname of the form Rcs/path or pathi/RCS/path2. The-x option 
can specify a list of suffixes separated by/. For example -x,v/ specifies two suffixes: ,v and the 
empty suffix. If two or more suffixes are specified, they are tried in order when looking for an RCS 
file; thefirst onethat works is used for that file. If no RCS file isfound but an RCSfilecan be 
created, the suffixes are tried in order to determinethenew RCS file’s name The default for 
suffixes is installation-dependent; normally it is ,v/ for hosts like U NIX that permit commasin 
filenames, and is empty (that is, just the empty suffix) for other hosts 
-zzone Specifiesthe date output format in keyword substitution, and specifiesthedefault time zonefor 

datein the-ddate option. The zone should be empty, a numeric UTC offset, or the special string 
lt for local time The default is an empty zone which uses the traditional RCS format of UTC 
without any timezone indication and with slashes separating the parts of the date otherwise times 
are output in ISO 8601 format with time zone indication. For example, if local time isj anuary 11, 
1990, 8 p.m. Pacific Standard Time eight hours west of UTC, then the time is output as follows 


Option 

Time Output 


-zLT 

-z+05:30 

1990/01/12 04:00 

1990-01-11 20:00 

1990-01-12 09:30 

00 (default) 


The-z option does not affect dates stored in RCS files, which arealwaysUTC. 


FILE NAMING 

Pairs of RCS files and working files can be specified in three ways. (See also "Examples" next.) 

1. Both the RCS file and the working file are given. The RCS pathname is of the form pathi/workfiiex and the working 
pathname is of the form path 2 /workfiie where pathi / and path 2 / are (possibly different or empty) paths, worktiie isa 
filename and x isan RCSsuffix. If x isempty, pathi/ must start with rcs / or must contain /rcs/. 

2. Only the RCS file is given. Then the working file is created in the current directory and its name is derived from the 
name of the RC S file by removing pathi / and the suffix x. 





3. Only the working file isgiven. Then ci considers each RCS suffix X in turn, looking for an RCS file of the form path 2 / 
Rcs/workfiiex or (if the former is not found and x is nonempty) path 2 /workfiiex. 

If the RCS file is specified without a path in one of the first two preceding scenarios, ci looksfor the RCS file first in the 
directory . / rcs and then in thecurrent directory. 

ci reports an error if an attempt to open an RCS file fails for an unusual reason, even if the RCS file's pathname is just one 
of several possibilities. For example, to suppress use of RCS commands in a directory d, create a regular file named d/RCSso 
that casual attempts to use RCS commands in d fail because d/RCS is not a directory. 

EXAMPLES 

Suppose ,v is an RCS suffix and thecurrent directory contains a subdirectory RCS with an RCSfileio.c.v. Then each of 
thefollowing commands checks in a copy of io.c into RCS/io.c,v as the latest revision, removing io.c: 


ci io.c; ci RCS/io.c,v; ci io.c.v; 



Suppose instead that the empty suffix is an RCS suffix and the current directory contains a subdirectory RCS with an RCS 
file io.c. Then each of the following commands checks in anew revision: 
ci io.c; ci RCS/io.c; 



FILE MODES 

An RCS file created by ci inherits the read and execute permissions from the working file If the RCS file exists already, ci 
preserves its read and execute permissions ci always turns off all write permissions of RCS files 

FILES 

Temporary files are created in the directory containing the working file, and also in the temporary directory. (See tmpdir 
under "Environment.") A semaphore file or files are created in the directory containing the RCS file. With a nonempty 
suffix, the semaphore names begin with the first character of the suffix; therefore, do not specify an suffix whose first 
character could be that of a working filename With an empty suffix, the semaphore names end with an underscore (_), so 
working filenames should not end in ci never changes an RCS or working file Normally, ci unlinks thefile and createsa 
new one; but instead of breaking a chain of one or more symbolic links to an RCS file, it unlinks the destination file instead. 
Therefore ci breaks any hard or symbolic links to any working file it changes; and hard links to RCS files are ineffective, but 
symbolic links to RC S files are preserved. 

The effective user must be able to search and write the directory containing the RCS file Normally, the real user must be 
able to read the RC S and working files and to search and write the directory containing the working file; however, some 
older hosts cannot easily switch between real and effective users, so on these hosts the effective user is used for all accesses 
The effective user isthesameasthereal user unless your copies of ciand co havesetuid privileges. These privileges yield 
extra security if the effective user owns all RCS files and directories and if only the effective user can write RCS directories. 
Users can control access to RCS files by setting the permissionsof the directory containing thefiles; only users with write 
access to the directory can useRCScommandsto change its RCS files For example, in hosts that allow a user to belong to 
several groups, one can make a group's RCS directories writable to that group only. This approach sufficesfor informal 
projects but it meansthat any group member can arbitrarily change the group's RCS files, and can even remove them 
entirely. Flence, more formal projects sometimes distinguish between an RCS administrator, who can change the RCS files 
at will, and other project members who can check in new revisions but cannot otherwise change the RCS files 

setuidUSE 

To prevent anybody but their RCS administrator from deleting revisions a set of users can employ setuid privileges as 
follows: 
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a Check that the host supports RCSsetuid use Consult a trustworthy expert if there are any doubts. It is best if the 
setuid system calls works as described in POSIX 1003.1a Draft 5, because RC Scan switch back and forth easily 
between real and effective users, even if the real user is root. If not, the second best is if the setuid system call supports 
saved setuid (the {_posix_saved_ids} behavior of POSIX 1003.1-1990); this fails only if the real or effective user is root. 
If RCS detects any failure in setuid, it quits immediately. 

■ C hoose a user A to serve as RCS administrator for the set of users. Only A can invoke the res command on the users' 
RCS files. A should not be root or any other user with special powers. M utually suspicious sets of users should use 
different administrators. 

■ C hoose a pathname B to be a directory of files to be executed by the users. 

■ H aveA sdt up B to contain copies of ciand co that are setuid to A by copying the commandsfrom their standard 
installation directory D asfollows: 

mkdir B cp D/c[io] B chmod go-w,u+s B/c[io] 

■ H ave each user prepend B to his/her path asfollows: 

PATH=B:$PATH; export PATH # ordinary shell 
set path=(B $path) # C shell 

■ H ave A create each RC S directory R with write access only to A asfollows: 

mkdir R chmod go-w R 

■ If you want to let only certain users read the RC S files, put the users into a group G, and have A further protect the RC S 
directory asfollows 

chgrp G Rchmod g-w,o-rwx R 

■ HaveA copy old RCS files (if any) into R, to ensure that A ownsthem. 

■ An RC S file'saccess list limits who can check in and lock revisions The default access list isempty, which grants 
checkin access to anyone who can read the RCS file If you want limit checkin access, have A invoke res -a on thefile; 
see rcs(l). In particular, res -e -aA limits access to just A. 

■ HaveA initialize any new RCS files with res -i before initial checkin, adding the -a option if you want to limit checkin 
access. 

■ Give setuid privileges only to ci, co, and rcsciean; do not give them to res or to any other command. 

■ Do not use other setuid commands to invoke RCS commands setuid is trickier than you think! 

ENVIRONMENT 

rcsinit Options prepended to the argument list, separated by spaces. A backslash escapes spaces within an option. 

The rcsinit options are prepended to the argument lists of most RCS commands Useful rcsinit options 
include -q, -v, -x, and -z. 

tmpdir N ame of the temporary directory. If not set, the environment variables tmp and tempso are inspected 

instead and the first value found is taken; if none of them are set, a host-dependent default is used, 
typically / tmp. 

DIAGNOSTICS 

For each revision, ci prints the RCS file the working file, and the number of both the deposited and the preceding revision. 
The exit status is zero if and only if all operations were successful. 

IDENTIFICATION 

Author: Walter F.Tichy. 

M anual page revision: 5.17; Release date 16 June 1995 
C opyright © 1982,1988,1989 W alter F. T ichy 
Copyright © 1990,1991,1992,1993,1994,1995 Paul Eggert 



cidentd 


SEE ALSO 

co(1), emacs(l), ident(l), make(l), rcs(l), rcsclean(l), rcsdiff(l), rcsintro(l), rcsmerge(l), rlog(l), setuid(2), rcsfile(5) 
Walter F. Tichy, "RCS—A System for Version Control," Software Practice & Experience 15, 7 (July 1985), 637-654. 

GNU, 16 ]unel995 


cidentd 

cidentd— identd Server 

SYNOPSIS 

cidentd [-usqvnah] [-f file] [-1 file] [-t seconds] 


DESCRIPTION 


cidentd gives authentication information. 

cidentd isan RFC 1314- and 931-compliant identd daemon. It accepts connections on a port (113 default) and answers 
queries for port owner of a connection, command; 


cidentd normally terminates when the remote command does The options are as follows: 

-u T urns on the use of the .authiie file in the user's home directory to give the requesting system whatever 

information the user provides Thisfile isoverri dden by the-a option and the system file the format is as 
follows: 

hideme # hide user id 


host-ip can bean ip in dot notation or a name. The file is set so that whatever comes last is what they get. 


Closes the connection after a single query. 

Quits the daemon after 1 connection (default in 1.0b). 

T urns on verbose logging to thesyslogs. 

M akes cident act li ke the old school identd with nothi ng sped al. 

E nables the/etc/cident. users file for options which overrides the user files if -u is specified. Theformat 
is as follows: 

username name-to-send # send this for username 

username # must send there username 

all name-to-send # send for every query 


d nothing every query 


them 


host-ip can bean ip in dot notation or a name. Thefile is set so that whatever comes last is what they get. 

-h Displays the help list to the screen you might not want to do thisfrom some terminal types. 

-f Sdts the file to find the ports and ids of connections. Use thisto specify a file other than /proc/net/tcp. 

-1 Used to specify a file other than /etc/cident. users must be used with the-a option unless you like 

redundancy. 

-t Sdts the time out of a connection in seconds. This does not work in this version to cidentd. 
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FI 


If no arguments are specified, the program just runs as normal, almost like the -n. 
cidentd -t 30 -a sets timer to 30 seconds and tells it to look at .authiie files 

FILES 

/etc/cidentd.users 
$(HOME)/.authlie 

SEE ALSO 

identd(l) 

BUGS 

None that I know of. 

Linux/FreeBSD, May 1996 


cksum 

cksum— C hecksum and count the bytes in a file 

SYNOPSIS 

cksum [-help] [-version] [file...] 

DESCRIPTION 

This manual page documents the GN U version of cksum. cksum computes a cyclic redundancy check (CRC) for each named 
file, or the standard input if none are given or when a file named - is given. It prints the CRC for each file along with the 
number of bytes in the file, and the filename unless no arguments were given. 

cksum is typically used to make sure that files transferred by unreliable means (such asnetnews) have not been corrupted. This 
is accomplished by comparing the cksum output for the received files with the cksum output for the original files. The CRC 
algorithm is specified by the POSIX.2 standard. It is not compatible with the BSD orSystemV sum programs; it is more 
robust. 

Availableoptionsare 

-help Print a usage message and exit with a nonzero status. 

-version Print version information on standard output then exit. 

GNU Text Utilities 


clear 

clear—Clear terminal screen 

SYNOPSIS 


DESCRIPTION 

clear calls tput(l) with the clear argument. T his causes tput to attempt to clear the screen, checking the data in /etc/termcap 
(for the GN U or BSD tput) or in theterminfo database (for the ncurses tput) and sending the appropriate sequence to the 
terminal. Thiscommand can be redirected to clear the screen of some other terminal. 




m 


SEE ALSO 

reset(l), stty(l), tput(l) 

AUTHOR 

Rik Faith (faith@cs.unc.edu) 

Linux0.99,10 October 1993 


cmuwmtopbm 

cmuwmtopbm—Convert a C M U window manager bitmap into a portable bitmap 

SYNOPSIS 

cmuwmtopbm [cmuwmfile] 

DESCRIPTION 

Reads a CM U window manager bitmap as input. Produces a portable bitmap as output. 

SEE ALSO 

pbmtocmuwm(l), pbm(5) 

AUTHOR 

Copyright © 1989 byJef Poskanzer 

15 April 1989 


CO 

CO- C heck out RC S revisions 

SYNOPSIS 

co [options] file ... 

DESCRIPTION 

co retrievesa revision from each RCS file and stores it into the corresponding working file. 

Pathnamesmatchingan RCS suffix denote RCS files; all others denote working files. Names are paired as explained in ct(l). 
Revisions of an RCS file can be checked out locked or unlocked. Locking a revision prevents overlapping updates. A revision 
checked out for reading or processing (for example, compiling) need not be locked. A revision checked out for editing and 
later checkin must normally be locked. Checkout with locking fails if the revision to be checked out is currently locked by 
another user. (A lock can be broken with rcs(l).) Checkout with locking also requires the caller to be on the access list of the 
RCS file, unless he is the owner of the file or the superuser, or the access list is empty. C heckout without locking is not 
subject to access list restrictions, and is not affected by the presence of locks. 

A revision isselected by options for revision or branch number, checkin date/time, author, or state. W hen theselection 
options are applied in combination, co retrieves the latest revision that satisfies all of them. If none of theselection options is 
specified, co retrieves the latest revision on the default branch, normally the trunk; see the -b option of rcs(l). A revision or 
branch number can be attached to any of the options -f, -i, -i, -m, -p, -q, -r, or -u. The options -d (date), -s (state), and -w 
(author) retrieve from a single branch, the selected branch (which is specified by -f or -u), or the default branch. 

A co command applied to an RCS file with no revisions creates a zero-length working file, co always performs keyword 
substitution. 
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H 

OPTIONS 


-1 [ r e v 


Retrieves the latest revision whose number is less than or equal to re#. If re* indicates a branch 
rather than a revision, the latest revision on that branch is retrieved. If rev is omitted, the latest 
revision on the default branch is retrieved; see the-b option of rcs(l). If re* is$, co determines the 
revision number from keyword valuesin the working file. Otherwise a revision iscomposed of one 
or more numeric or symbolic fields separated by periods If re* begins with a period, then the 
default branch (normally the trunk) is prepended to it. If rev isa branch number followed by a 
period, then the latest revision on that branch is used. The numeric equivalent of a symbolic field is 
specified with the-n option of the commands ci(l) and rcs(l). 

Same as -r, except that it also locks the retrieved revision for the caller. 

Same as -r, except that it unlocks the retrieved revision if it was locked by the caller. If rev is 
omitted, -u retrieves the revision locked by thecaller, if there isone; otherwise it retrieves the latest 
revision on the default branch. 

Forces the overwriting of the working file; useful in connection with -q. (See also "File M odes," 
later in this manual page.) 

Generate keyword strings using the default form, for example, $Revision: 5.13 $ for the Revision 
keyword. A locker's name is inserted in the value of the Header, id, and Locker keyword strings only 
as a file is being locked, that is, by d -landco - 1 . This isthe default. 

Like -kkv, except that a locker's name is always inserted if the given revision is currently locked. 
Generate only keyword names in keyword strings; omit their values. (See "Keyword Substitution," 
later in this manual page.) For example, for the Revision keyword, generate the string $Revision$ 
instead of $Revision: 5 .i 3 $. This option isuseful to ignore differences due to keyword substitu¬ 
tion when comparing different revisionsof a file. Log messages are inserted after $Log$ keywords 
even if-is* isspecified, since this tends to be more useful when merging changes. 

Generate the old keyword string, present in the working file just before it was checked in. For 
example, for the Revision keyword, generate the string $Revision: 1.1 $ instead of $Revision: 5.13 
$ if that is how the string appeared when the file was checked in. Thiscan be useful for file formats 
that cannot tolerate any changes to substrings that happen to taketheform of keyword strings 
Generate a binary image of the old keyword string. This acts like -ko, except it performs all 
working file input and output in binary mode. This makes little difference on POSIX andUNIX 
hosts,but on DOS-like hosts one should use res -i -kb to initialize an RCS file normally refuses 
to merge files when -kb isin effect. 

Generate only keyword values for keyword strings. For example for the Revision keyword, generate 
thestring 5.13 instead of$Revision: 5.13 $.Thiscan help generate files in programming languages 
where it is hard to strip keyword delimiters like $Revision: $ from a string. FI owever, further 
keyword substitution cannot be performed once the keyword names are removed, so this option 
should be used with care. Because of this danger of losing keywords, thisoption cannot be 
combined with - 1 , and the owner write permission of the working file isturned off; to editthefile 
later, check it out again without -kv. 

Prints the retrieved revision on the standard output rather than storing it in the working file This 
option isuseful when co is part of a pipe 
Q uiet mode; diagnostics are not printed. 

Interactive mode the user is prompted and questioned even if the standard input is not a terminal. 
Retrieves the latest revision on the selected branch whose checkin date/time isless than or equal to 
date The date and time can be given in free format. The time zone lt stands for local time; other 
common time zone names are understood. For example, the following dates are equivalent if local 
timeisjanuary 11,1990, 8 p.m. Pacific Standard Time, eight hours west of Coordinated Universal 
Time(UTC): 

8:00 PM It 

4:00 AM ,Jan. 12,1990 Default isUTC 
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1990-01-12 04:00:00400 ISO 8601 (UTC) 

1990-01-11 20:00:00-08 ISO 8601 (local time) 

1990/01/12 04:00:00 Traditional RCSformat 

Thu Jan 11 20:00:00 1990 LT O utput of ctime(3) 4-LT 

Thujan 11 20:00:00 PST 1990 Output of date(l) 

Fri Jan 12 04:00:00GMT 1990 

Thu, 11 Jan 1990 20:00:00 -0800 Internet RFC 822 

12-January-1990,04:00 WET 

Most fields in the date and time can bedefaulted. The default time zone is normally UTC, butthiscan be overridden by the 
-z option. Theother defaults are determined in theorder year, month, day, hour, minute, and second (most to least 
significant). At least one of these fields must be provided. For omitted fields that are of higher significance than the highest 
provided field, thetimezone'scurrent values are assumed. For all other omitted fields, the lowest possible values are 
assumed. For example without -z, thedate20,10:30 defaults to 10:30:00 UTC of the 20th of the UTC time zone's current 
month and year. Thedat^timemust be quoted if it contains spaces. 

-m [rev ] Sets the modification timeon the new working fileto be the date of the retrieved revision. Usethis 

option with care it can confuse make(l). 

-sstate Retrievesthe latest revision on the selected branch whose state is set to state. 

-t Preserves the modification time on the RC S file even if the RC S file changes because a lock is 

added or removed. This option can suppress extensive recompilation caused by amake(l) depen¬ 
dency of some other copy of the working file on the RCS file. Usethisoption with care; it can 
suppress recompilation even when it is needed, in other words, when the change of lock would 
mean a change to keyword strings in the other working file. 

-w[i agin] Retrieves the latest revision on the selected branch that was checked in by the user with login name 

i og i n . If the argument login is omitted, the caller's logi n is assumed. 

-jj oi ni i st Generates a new revision which is the join of the revisions on j o ni i s t . This option is largely made 

obsolete by rcsmerge(l), but is retained for backwards compatibility. 

Thej oi niist isacomma-separatedlistofpairsoftheformre*2:rev3,wherere»2 and rev3 are 
(symbolic or numeric) revision numbers For the initial such pair, revi denotes the revision selected 
by the options -f, -w. For all other pairs, revi denotes the revision generated by the previous pair. 
(Thus the output of one join becomes the input to the next.) 

For each pair, co joinsrevisionsr ev l and r ev3 with respect to r ev 2 . Thismeansthat all changes that 
transform re v 2 into revi are applied to a copy of re v3. This is particularly useful if revi and r ev 3 
are the ends of two branches that haver ev 2 asa common ancestor. If r e v i <r ev 2 <r ev 3 on thesame 
branch, joining generates a new revision which is like r ev3 , but with all changes that lead from revi 
to r e v 2 undone If changesfrom rev 2 to revi overlap with changes from re v 2 to rev3, co reports 
overlaps as described in merge(l). 

Fortheinitial pair, rev 2 can be omitted. The default isthe common ancestor. If any of the 
arguments indicate branches, the latest revisionson those branches are assumed. The options -i 
and -u lock or unlock revi. 

-v PrintsRCS'sversion number. 

-vn Emulates RCS version n, where n can be 3,4, or 5. This can be useful when interchanging RCS 

fi les with others who are running older versions of RC S. To see which version of RC S your 
correspondents are running, have them invoke res -v; this works with newer versionsof RCS. If it 
doesn't work, have them invokeriog on an RCSfile; if noneof the first few lines of output contain 
the string branch:, it is version 3; if the dates' years have just two digits, it is version 4; otherwise, it 
is version 5. An RCS file generated while emulating version 3 loses its default branch. An RCS 
revision generated while emulating version 4 or earlier has a timestamp that is off by up to 13 
hours A revision extracted whileemulating version 4 or earlier contains abbreviated dates of the 
form yy/mm/dd and can also contain different whitespace and line prefixes in the substitution for 

$Log$. 
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U ses suffixes to characterize RC S files See ci(l) for details 

Specifies the date output format in keyword substitution, and specifies the default time zonefor 
datein the-ddate option. The zone should be empty, a numeric UTC offset, or the special string 
lt for local time The default is an empty zone which uses the traditional RCS format of UTC 
without any time zone indication and with slashes separating the parts of the date otherwise times 
are output in ISO 8601 format with time zone indication. For example, if local time isjanuary 11, 
1990, 8 p.m. Pacific Standard Time eight hours west of UTC, then the time is output as follows 

Option TimeOutput 


-z 1990/01/12 04:00:00 (default) 

-zLT 1990-01-11 20:00:00-08 

-z+05:30 1990-01-12 09:30:00+05:30 

The-z option does not affect dates stored in RCSfiles, which arealwaysUTC. 


KEYWORD SUBSTITUTION 

Strings of the form $ keyword $ and $ keyword : ... $embeddedinthetextarereplacedwithstringsoftheform$ keyword 
: value $, where key word and value are pairs in thefollowing list. Keywords can beembedded in literal strings or comments 
to identify a revision. 

Initially, the user enters strings of theform $keyword$. On checkout, co replaces these strings with strings of theform 
$k e y wo r d : vai ue$. If a revision containing stringsof the latter form ischecked back in, thevai ue fields will be replaced 
during the next checkout. T hus, the keyword values are automatically updated on checkout. T hisautomatic substitution can 
be modified by the -k options 
Keywords and their corresponding values: 

$Aut hor $ The login name of the user who checked in the revision. 

$Date$ The date and time the revision was checked in. With -zz one, a numeric time zone offset is 

appended; otherwise the date is U TC. 

$He a d e r $ A standard header containingthefull pathname of the RCS file the revision number, thedateand 

time, the author, the state, and the locker (if locked). With -zzone, a numeric time zone offset is 
appended to the date; otherwise, the date is U TC. 

$i d $ Same as$Header $, except that the RC S filename is without a path. 

$l o c k e r $ The login name of the user who locked the revision (empty if not locked). 

$l o g $ The log message supplied during checkin, preceded by a header containing the RCS filename the 

revision number, the author, and thedateand time With -zzone a numeric time zone offset is 
appended; otherwise the date is U TC. Existing log messages are not replaced. I nstead, the new log 
message is inserted after $Log: ... $. T his is useful for accumulating a complete change log in a 
source file. 

Each inserted line is prefixed by the string that prefixes the $ug$ line. For example, if the $Log $ line is// $Log: tan.ee $, 
RCS prefixes each line of the log with / /. T his is useful for languages with comments that go to the end of the line T he 
convention for other languages is to use a * prefix inside a multiline comment. For example, the initial log comment of a C 
program conventionally is of thefollowing form: 

* $Log$ 

For backwardscompatibility with older versions of RCS, if the log prefix is/* or (* surrounded by optional whitespace 
inserted log lines contain a space instead of / or <; however, this usage is obsolescent and should not be relied on. 

$Name$ The symbolic name used to check out the revision, if any. For example co -r Joe generates $Name: 

joe $. Plain co generatesjust $Name: $. 
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$RCSf i e$ ThenameoftheRCSfilewithoutapath. 

$Rev i si on$ Therevision number assigned to therevision. 

$s o u r c e $ Thefull pathname of the RC S file. 

$st at e$ The state assigned to the revision with the-s option of rcs(l) or ci(l). 

Thefollowing characters in keyword values are represented by escape sequences to keep keyword strings well-formed. 
Character Exape Sequence 

tab \t 

newline \n 

space \040 

$ \044 

\ \\ 

FILE MODES 

The working file inherits the read and execute permissionsfrom the RCS file. In addition, theowner write permission is 
turned on, unless -kv is set or the file is checked out unlocked and locking issetto strict; see rcs(l). 

If a file with the name of the working file exists already and has write permission, co aborts the checkout, asking beforehand 
if possible. If the existing working file is not writable or -f isgiven, the working file is deleted without aski ng. 

FILES 

co accesses files much as ci(l) does, except that it does not need to read the working file unless a revision number of $ is 
specified. 

ENVIRONMENT 

rcsinit 0 ptions prepended to the argument list, separated by spaces. See ci(l) for detai Is 

DIAGNOSTICS 

The RCS pathname the working pathname, and therevision number retrieved are written to the diagnostic output. The exit 
status is zero if and only if all operations were successful. 

IDENTIFICATION 

Author: Walter F.Tichy. 

M anual Page Revision: 5.13; Release D ate: 1995/06/01. 

Copyright © 1982,1988,1989 Walter F. Tichy. 

Copyright © 1990,1991,1992,1993,1994,1995 Paul Eggert. 

SEE ALSO 

rcsintro(l), ci(l), ctime(3), date(l), ident(l), make(l), rcs(l), rcsclean(l), rcsdiff(l), rc-smerge(l), rlog(l), rcsfile(5) 
Walter F. Tichy, "RCS-A System for Version Control," Software Practice & Experience 15,7 (July 1985), 637-654. 

LIMITS 

Links to the RC S and working files are not preserved. 

There is no way to selectively suppress the expansion of keywords, except by writing them differently. In nroff and troff, 
this is done by embedding the null-character \&into the keyword. 


GNU, 1 Junel995 
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col 

coi— Filter reverse line feeds from input 

SYNOPSIS 

col [-bfx] [-1 num] 

DESCRIPTION 

coi filters out reverse (and half-reverse) linefeeds so the output is in the correct order with only forward and half-forward 
linefeeds, and replaces whitespace characters with tabs where possible. Thiscan be useful in processing the output of 
nrotf(l) and tbi(l). coi reads from standard input and writes to standard output. 

The options are asfollows 

-b D o not output any backspaces, printing only the last character written to each column position. 

-t Forward half-linefeeds are permitted (fine mode). N ormally characters printed on a half-line boundary 

are printed on thefollowing line 
-x Output multiple spaces instead of tabs 

-inum Buffer at least num lines in memory. By default, 128 lines are buffered. 

The control sequences for carriage motion that coi understands and their decimal values are listed in thefollowing table 


Control Sequence 

Esc+7 

Esc+8 

Esc 49 

Backspace 

Carriage return 

Newline 

Shift in 

Shift out 

Space 

Tab 

Vertical tab 


D edmal Value 

Reverse linefeed (escapethen 7) 

Half-reverse line feed (escape then 8) 

Half-forward linefeed (escapethen 9) 

Moves back one column (8); ignored in the first column 
(13) 

Forward linefeed (10); also does carriage return 
Shift to normal character sdt (15) 

Shift to alternate character set (14) 

M oves forward one column (32) 

M oves forward to next tab stop (9) 

Reverse linefeed (11) 


All unrecognized control characters and escape sequences are discarded. 

coi keeps track of the character set as characters are read and makes sure the character set is correct when they are output. 
If the input attempts to back up to the last flushed line, coi will display a warning message. 


SEE ALSO 

expand(l), nroff(l), tbl(l) 


HISTORY 

A coi command appeared in version 6 AT&T UN IX. 


17Junel991 
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colcrt 

coicrt— Filter nroff output for C RT previewing 

SYNOPSIS 

colcrt [-] [-2] [file ...] 

DESCRIPTION 

coicrt provides virtual half-line and reverse-linefeed sequencesfor terminals without such capability, and on which 
overstriking is destructive Half-line characters and underlining (changed to dashing-) are placed on new lines in between 
the normal output lines 
Available options: 

Suppress all underlining. Thisoption isespeci ally useful for previewing all boxed tables from tbi(l). 

-2 Causes all half-linesto be printed, effectively double spacing the output. N ormally, a minimal space 

output format is used which will suppress empty lines. The program never suppresses two consecutive 
empty lines however. The -2 option is useful for sending output to the line printer when the output 
contains superscripts and subscripts that would otherwise be invisible 

EXAMPLES 

A typical use of coicrt would be 

tbl exum2.n ] nroff -ms | colcrt - | more 

SEE ALSO 

nroff(l), troff(l), col(l), more(l), ul(l) 

BUGS 

Should fold underlines onto blanks even with the - option so that a true underline character would show. 

Can't back up more than 102 lines 

General overstriking is lost; as a special case | overstruck with " or underline becomes+. Linesaretrimmed to 132 
characters. 

Some provision should be made for processing superscripts and subscripts in documents that are already double-spaced. 

HISTORY 

The coicrt command appeared in BSD 3.0. 

BSD 3, 30 Junel993 


colrm 

coirm— Remove columnsfrom a file 

SYNOPSIS 

colrm [startcol [ended ]] 

DESCRIPTION 

coirm removes selected columnsfrom a file. Input is taken from standard input. Output is sent to standard output. 

If called with one parameter, the columns of each line will be removed starting with the specified column. If called with two 
parameters the columnsfrom thefirst column to the last column will be removed. 

Column numbering starts with column 1. 
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SEE ALSO 

awk(l), column(l), expand(l), paste(l) 

HISTORY 

The coirm command appeared in BSD 3.0. 

BSD 3,14 March 1991 


column 

column— Columnate lists 

SYNOPSIS 

column [-tx] [-ccolumns] [-ssep ] [...file] 

DESCRIPTION 

The column utility formats itsinput into multiple columns Rows are filled before columns Input istaken from file operands, 
or, by default, from the standard input. Empty lines are ignored. 

The options are asfollows 

-c Output isformatted for a display columns wide 

-s Specify a set of characters to be used to delimit columnsfor the -t option. 

-t D eterminethe number of columnsthe input containsand create a table. Columns are delimited with 

whitespace, by default, or with the characters supplied using the -s option. Useful for pretty-printing 
displays 

-x Fill columns before filling rows. 

Column exits 0 on success >0 if an error occurred. 

ENVIRONMENT 

The environment variable columns is used to determine the size of the screen if no other information is available. 

EXAMPLES 

(printf "PERM LINKS OWNER SIZE MONTH DAY HH:MM/YEAR NAME"; Is -1 j sed Id) j column -t 

SEE ALSO 

colrm(l), ls(l), pasted), sort(l) 

HISTORY 

The column command appeared in BSD 4.3 Reno. 

6Junel993 


comm 

comm- Compare two sorted files line by line 

SYNOPSIS 

comm [-123] [—help] [—version] filel f i I e 2 
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DESCRIPTION 

This manual page documents the GN U version of comm, comm prints lines that are common, and lines that are unique to two 
input files. The two files must be sorted before comm can be used. The filename- means the standard input. 

With no options, comm produces three column output. Column one contains lines unique to f i i ei, column two contains 
lines unique to f i i e2 , and column three contains lines common to both files 

OPTIONS 

Theoptions-i, -2, and -3 suppress printing of the corresponding columns 
-help Print a usage message and exit with a nonzero status. 

-version Print version information on standard output then exit. 
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convdate- Convert timefdate strings and numbers 

SYNOPSIS 

convdate [ -c ][-n ][-s ] arg... 

DESCRIPTION 

convdate translates the date/time strings specified as arguments on its command line, outputting the results oneto a line. 
If the -s flag is used, then each argument is taken as a date string to be parsed by parse-date(3) and isoutput asa string 
formatted by cttme(3). This is the default. 

If the -n flag is used, then each argument isconverted the same way but isoutput as a timet; see time(2). 

If the -c flag is used, then each argument i s taken to be a timet and isoutput in ctime format. 

H ere's an example 

% convdate 1 feb 10 10am' 

Sun Feb 10 10:00:00 1991 


% convdate 12pm 5/4/90 
Fri Dec 13 00:00:00 1991 
Fri May 4 00:00:00 1990 

% convdate -n 1 feb 10 10am 1 '12pm 5/4/90 

666198000 

641880000 

% convdate -c 666198000 
Sun Feb 10 10:00:00 1991 

HISTORY 

Written by Rich $alz (rsalz@uunet.uu.net). 

SEE ALSO 

parsedate(3) 
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cp 

cp—Copy files 

SYNOPSIS 

cp [options] source dest 
cp [options] source... directory 

Options: 

[-abdfilprsuvxPR] [-S backup-suffix] [-V fnumbered,existing,simpleg] [-backup] 
[-no-dereference] [—force] [—interactive] [-one-file-system] [ — preserve] 

[-recursive] [— update] [—verbose] [ — suffix=backup-suffix] 

[ — version-control^fnumbered,existing,simpleg] [-archive] [-parents] [-link] 
[-symbolic-link] [-help] [-version] 


DESCRIPTION 

This manual page documents the GN U version of cp. If the last argument names an existing directory, cp copies each other 
given file into a file with the same name in that directory. 0 therwise if only two files are given, it copies the first onto the 
second. It is an error if the last argument is not a directory and more than two files are given. By default, it does not copy 
directories. 


OPTIONS 

-a, —archive 

-b, —backup 

-d, —no-dereference 

-1, -interactive 
-1, -link 
-P, -parents 


-s, -symbolic-link 


-u, —update 

-v, -verbose 
-x, -one-file-system 
-R, -recursive 
-help 

-S, -suffix backup-suffix 


Preserve as much as possible of the structure and attributes of theoriginal filesin the copy. 
The same as-dpR. 

M ake backups of files that are about to be overwritten or removed. 

Copy symbolic links as symbolic links rather than copying thefiles that they point to, and 

preserve hard link relationships between source filesin the copies 

Remove existing destination files 

Prompt whether to overwrite existing regular destination files 

M ake hard links instead of copies of nondirectories 

Form the name of each destination file by appending to the target directory a slash and the 
specified name of the source file. The last argument given to cp must be the name of an 
existing directory. For example the command cp -parents a/b/c existing_dir copies the 
file a/b/c to existing_dir/a/b/c, creating any missing intermediate directories 
Preserve the original files' owner, group, permissions and timestamps. 

Copy directories recursively, copying all nondirectories as if they were regular files 
M ake symbolic links instead of copies of nondirectories. All source filenames must be 
absolute (starting with /) unless the destination files arein the current directory. This 
option produces an error message on systems that do not support symbolic links. 

Do not copy a nondirectory that has an existing destination with thesame or newer 
modification time 

Print the name of each file before copying it. 

Skip subdirectories that are on different filesystems from the one that the copy started on. 
Copy directories recursively. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output then exit successfully. 

The suffix used for making simple backup files can beset with the simple_backup_suffix 
environment variable, which can be overridden by this option. If neither of those is given, 
the default is-, as it is in emacs. 
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-v, -version-control T he type of backups made can besetwith thevERSiON_coNTROL environment variable, which 

{numbered, existing, simple} can be overridden by thisoption. If version_control is not sdt and this option is not given, 
the default backup type is existing. The value of the version_control environment variable 
and the argument to thisoption are liketheG N U emacs version- control variable; they 
also recognize synonymsthat are more descriptive. The valid values are (unique abbrevia¬ 
tions are accepted) thefollowing: 

t or numbered Always make numbered backups 

nil or existing Make numbered backups of files that already have them, 

si mple backups of the others 
never or simple Always make simple backups 


cccp, cpp 

coop, cpp—TheGN U C-compatiblecompiler preprocessor 

SYNOPSIS 

cccp [-$][-A predicate [( value )]] [ -C ][-D name [ = definition ]] 
[-dD][-dM][-I\ directory ] [-H ][-I- ][-imacros file ][- 
include f i I e ][-idirafter di r ][-iprefix pref i * ][-iwithprefix di r ] 
[ -lang-c] [-lang-c++] [-lang-objc ] [-lang-ob]'c++ ] [-lint ][- 
M[-MG ]] [ -MM[-MG ]] [ -MD file ][-MMD file ][-nostdinc ] 

[ -nostdinc++][-P][-pedantic [[-pedantic-errors [[-traditional ] 

[ -trigraphs ][-U name [[-undef ][-Wtrigraphs [[-Wcomment ] 

[ -Wall ][-Wtraditional ] 

[infile !- ][ outfile |- ] 


DESCRIPTION 

TheC preprocessor isa macro processor that isused automatically by theC compiler to transform your program before 
actual compilation. It iscalled a macro processor because it allows you to define macros, which are brief abbreviationsfor 
longer constructs. 

TheC preprocessor provides four separate facilities that you can use as you see fit: 

■ Inclusion of header files. These are files of declarations that can besubstituted into your program. 

■ M aero expansion. You can define macros, which are abbreviationsfor arbitrary fragments of C code, and then theC 
preprocessor will replacethe macros with their definitions throughout the program. 

■ Conditional compilation. Using special preprocessing directives, you can include or exclude parts of the program 
according to various conditions 

■ Linecontrol. Ifyou useaprogramtocombineorrearrangesourcefilesintoan intermediatefilewhich isthen compiled, 
you can use line control to inform the compiler of where each source lineoriginally came from. 

C preprocessors vary in some details For afull explanation of theGNU C preprocessor, see the info file cpp. info, or the 
manual TheC Preprocessor. Both of these are built from the same documentation source file, cpp. texinfo. TheGNU C 
preprocessor provides a superset of the features of AN SI Standard C. 

ANSI StandardC requires the rqection of many harmless constructs commonly used by today's C programs Such 
incompatibility would be inconvenient for users, so the G N U C preprocessor is configured to accept these constructs by 
default. Strictly speaking, to get AN SI Standard C, you must use the options -trigraphs, -undef, and -pedantic, but in 
practice the consequences of having strict AN SI Standard C make it undesirable to do this 

When you use theC preprocessor, you will usually not have to invoke it explicitly: theC compiler will do so automatically. 

H owever, the preprocessor issometimes useful individually. 

W hen you call the preprocessor individually, either name (cpp or cccp) will do; they are completely synonymous. 
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TheC preprocessor expects two filenames as arguments, mnie and outfiie. The preprocessor reads inf lie together with 
any other files it specifies with #inciude. All the output generated by the combined input files is written in outfiie. Either 
infiie or outfiie maybe-, which asinfiie means to read from standard input and as outfiie means to write to standard 
output. Also, if outfiie or both filenames are omitted, thestandard output and standard input are used for the omitted 
filenames. 


OPTIONS 


H ere isa table of command options accepted by the C preprocessor. These options can also be given when compiling a C 
program; they are passed along automatically to the preprocessor when it is invoked by the compiler. 


-traditional 


Inhibit generation of # lines with line-number information in the output from the preprocessor. 
This might be useful when running the preprocessor on something that is note code and will be 
sent to a program which might be confused by the# lines. 

Do not discard comments: pass them through to the output file Commentsappearing in 
arguments of a macro call will be copied to the output before the expansion of the macro call. 

T ry to imitate the behavior of old-fashioned C, as opposed to AN SI C. 


-trigraphs ProcessANSI standard trigraph sequences. These are three-character sequences, all starting with ??, 

that are defined by AN SI C to stand for single characters. For example ??/ stands for \,so ??/n isa 
character constant for a newline. Strictly speaking, theG N U C preprocessor does not support all 
programs in AN SI Standard C unless -trigraphs is used, but if you ever notice the difference it 
will be with relief. You don't want to know any more about trigraphs. 

-pedantic Issuewarningsrequired by theAN SI C standard in certain casessuch as when text other than a 

Comment follows #else Or #endif. 


-pedantic-errors 


-Wtrigraphs 

-Wcomment 

-Wcomments 


Like -pedantic, except that errors are produced rather than warnings. 

Warn if any trigraphs are encountered (assuming they are enabled). 

W arn whenever a comment-start sequence /* appears in a comment. (Both forms have the 
same effect.) 


-Wall 


Requests both -Wtrigraphs and -Wcomment (but not -Wtraditional). 


-Wtraditional 


Warn about certain constructs that behave differently in traditional andANSI C. 

Add the directory di rectory to the end of the list of directories to be searched for header files This 
can be used to override a system header file, substituting your own version, since these directories 
are searched before the system header file directories If you use more than one-i option, the 
directories are scanned in left-to-right order; thestandard system directories come after. 

Any directories specified with -i options before the-i- option are searched only for the case of 
#inciude 11 file ■; they are not searched for #inciude < file >. 

If additional directories are specified with -i options after the-i-, these directories are searched for 
all #inciude directives. 


-nostdinc 


In addition, the-i- option inhibits the use of the current directory as the first search directory for 
#inciude 11 file T herefore the current directory is searched only if it is requested explicitly with 
-i followed by a period (.). Specifying both -i- and -i. allows you to control precisely which 
directories are searched before the current one and which are searched after. 

Do not search thestandard system directories for header files. Only the directories you have 
specified with -i options (and the current directory, if appropriate) are searched. 

D o not search for header files in the C -t+specific standard directories, but do still search the other 
standard directories. (Thisoption is used when building iibg++.) 

Predefinename asamacro, with definition i. 

Predefine name as a macro, with definition def i ni ti o n . T here are no restrictions on thecontentsof 
definition, but if you are invoking the preprocessor from a shel I or shell-like program, you may 
need to use the sheH'squoting syntax to protect characters such as spaces that have a meaning in 
the shell syntax. If you use more than one-D for the same name, the rightmost definition takes 
effect. 





—M [ —MG] 


-imacros file 


-include fi 
-idirafter 


-iprefix prefix 
■iwithprefix dir 


-lang-objc 

-lang-objc++ 


Do not predefine name. If both -uand -d are specified for one name, the -u beatsthe-Dandthe 
name is not predefined. 

D o not predefine any nonstandard macros. 

Assert (in the same way asthe#assert directive) the predicate name with tokeniist value. 
Remember to escape or quote the parentheses on shell command lines You can use -a- to disable 
all predefined assertions it also undefines all predefined macros 
I nstead of outputting the result of preprocessing, output a list of #def ine directives for all the 
macros defined during the execution of the preprocessor, including predefined macros Thisgives 
you a way of finding out what is predefined in your version of the preprocessor; assuming you have 
no fi le f oo. h, the command 

touch foo.h; cpp -dM foo.h 

will show the values of any predefined macros 

Like -dM except in two respects: it does not include the predefined macros, and it outputs both the 
#define directives and the result of preprocessing. Both kinds of output go to the standard output 
file. 

I nstead of outputting the result of preprocessing, output a rule suitable for make describing the 
dependencies of the main source file T he preprocessor outputsone make rule containing the 
object filename for that source file, a colon, and the names of all the included files. If there are 
many included files then the rule is split into several lines using \\ (newline). 

-mg says to treat missing header files as generated files and assumethey live in the same directory as 
the source file. It must be specified in addition to -m. 

Thisfeatureisused in automatic updating of makefiles. 

Like -m but mention only thefiles included with #inciude ■ file ". System header files included 
with #inciude < file >areomitted. 

Like -m but the dependency information is written to file. This is in addition to compiling the file 
as specified, -md does not inhibit ordinary compilation the way -m does 
When invoking gcc, do not specify the fii e argument, gcc will create filenames made by replacing 
. c with . d at the end of the input filenames 

In M ach.youcan usetheutility md to merge multiple files into a single dependency filesuitable for 
using with the make command. 

Like -m except mention only user header files, not system header files 
Print the name of each header file used, in addition to other normal activities. 

Processfileas input, discarding the resulting output, before processing the regular input file. 
Because the output generated from file is discarded, the only effect of -imacros file isto make the 
macros defined in file availablefor use in the main input. The preprocessor evaluates any -d and -u 
optionson the command line before processing-imacros file. 

Processf i i e as input, and include all the resulting output, before processing the regular input file. 
Add the directory di r to the second include path. The directories on the second include path are 
searched when a header file is not found in any of thedirectories in the main include path (theone 
that-i adds to). 

Specify p r ef i x as the prefix for subsequent -iwithprefix options 

Add a directory to the second include path. The directory's name is made by concatenating prefix 
and dir, where prefix was specified previously with -iprefix. 

Specify the source language -iang-c++ makes the preprocessor handle C++comment syntax, 
and includes extra default include directories for C++, and -lang-objc enables the 0 bjective C 
#import directive -iang-c explicitly turnsoff both of these extensions and -iang-objc++ enables 
both. These options are generated by the compiler driver gcc, but not passed from the gcc 
command line 

Look for commands to the program checker lint embedded in comments, and emit them preceded 
by #pragma lint. For example thecomment /* notreached ‘/becomes #pragma lint notreached. 
This option is available only when you call cpp directly; gcc will not pass it from its command line. 
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-$ Forbid the use of $ in identifiers. This is required for AN SI conformance gcc automatically 

supplies this option to the preprocessor if you specify-ansi, but gcc doesn't recognize the-$ 
option itself; to use it without the other effects of -ansi, you must call the preprocessor directly. 

SEE ALSO 

cpp entry in info; TheC Preprocessor, Richard M . Stallman. 

gcc(l); gcc entry in info; Usng and Porb'ngGNU CC (for version 2.0), Richard M . Stallman. 

COPYING 

Copyright© 1991,1992,1993 Free Software Foundation, Inc. Permission isgranted to make and distribute verbatim 
copies of this manual provided the copyright notice and this permission notice are preserved on all copies 
Permission isgranted to copy and distribute modified versions of this manual under the conditionsfor verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to thisone. 
Permission isgranted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in theoriginal English. 

GNU Tools 30 April 1993 



crontab 

crontab— M anipulate per-user crontabs (D illon's C ron) 


SYNOPSIS 

crontab file [-u user ] 
crontab ■ [-u user] 
crontab -1 [user ] 
crontab -e [user ] 
crontab -d [user ] 
crontab -c di r 


Replace crontab from file 
Replace crontab from stdin 
List crontab for user 
Edit crontab for user 
D elete crontab for us er 
Specify crontab directory 


DESCRIPTION 

crontab manipulates the crontab for a particular user. 0 nly the superuser may specify a different user and/or crontab 
directory. Generally, the -e option isused to edit your crontab. crontab will use/usr/bin/vi or theeditor specified by your 
VISUAL environment variableto edit the crontab. 


U nlike other crond/crontabs, this crontab does not try to do everythi ng under the sun. Frankly, a shell script is much more 
able to manipulate the environment than cron, and I see no particular reason to use the user's shell (from his password entry) 
to run cron commands when this requires special casing of nonuser crontabs, such as those for UUCP. When a crontab 
command is run, thiscrontab runs it with /bin/sh and sets up only three environment variables: user, home, and shell. 
crond automatically detects changes in the time Reverse-indexed time changes less then an hour old will NOT rerun crontab 
commands already issued in the recovered period. Forward-indexed changes less then an hour into the future will issue 
missed commands exactly once Changes greater then an hour into the past or future cause crond to resynchronize and not 
issue missed commands No attempt will be made to issue commands lost due to a reboot, and commandsare not reissued if 
the previously issued command isstill running. For example if you have a crontab command sleep 70 that you wish to run 
once a minute, cron will only be able to issue the command once every two minutes If you do not likethisfeature, you can 
run your commands in the background with an &. 




T he crontab format is roughly similar to that used by vixiecron, but without complex features. I ndi vidual fields may contain 
a time a time range, a time range with a skip factor, a symbolic range for the day of week and month in year, and additional 
subranges delimited with commas. Blank lines in the crontab or lines that begin with a hash (#) are ignored. If you specify 
both a day in the month and a day of week, the result is effectively ORd; the crontab entry will be run on the specified day of 
week and on the specified day in the month. 

# MIN HOUR DAY MONTH DAYOFWEEK COMMAND 

# at 6:10 a.m. every day 
10 6 ***date 

# every two hours at the top of the hour 
0 *12 ***date 

# every two hours from 11p.m. to 7a.m., and at 8a.m. 

0 23-7/2,8 ***date 

0 11 4 * mon-wed date 

# 4:00 a.m. on january 1st 
0 4 1 jan 'date 


# once an hour, all output appended to log file 
0 4 1 ]an *date»/var/log/messages 2>&1 

The command portion of the line is run with /bin/sh -c <command>, and may therefore contain any valid Bourne shell 
command. A common practice isto run your command with exec to keep the processtable uncluttered. It is also common to 
redirect output to a log file. If you do not, and the command generates output on stdout or stderr, the result will be mailed 
to the user in question. If you use this mechanism for special users, such asUUCP, you may want to create an alias for the 
user to direct the mail to someone else, such as root or postmaster. 

Internally, this cron uses a quick indexing system to reduce CPU overhead when looking for commands to execute Several 
hundred crontabswith several thousand entries can be handled without using noticeable CPU resources. 

BUGS 

Ought to be able to have several crontab files for any given user, as an organizational tool. 

AUTHOR 

M atthew D illon (dlllon@apollo.west.olc.com) 

1 May 1994 


csplit 

csput— Split a file into sections determined by context lines 

SYNOPSIS 

csplit [-sqkz] [-f prefix] [-b suffix] [-n digits] [-prefix=prefix] 

[-suffix-format=suffix] [ —digits=digits] [—quiet] [ — silent] 

[-keep-files] [-elide-empty-files] [-help] [ — version] 
file pattern... 

DESCRIPTION 

This manual page documents the GN U version of csplit. csplit creates zero or more output files containing sections of the 
given input file or the standard input if the name - is given. By default, csplit prints the number of bytes written to each 
output file after it has been created. 
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The contents of the output fils are determined by the pattern arguments. An error occurs if a pattern argument refers to a 
nonexistent line of the input file, such as if no remaining line matchs a given regular expression. After all the given patterns 
have been matched, any remaining output is copied into one last output file. Thetypsof pattern argumentsare 


/regexp/[offset] 


%regexp%[offset] 

{repeat-count} 


Create an output file containing the current lineup to (but not including) line line (a positive 
integer) of the input file If followed by a repeat count, also create an output file containing the 
next line lins of the input file once for each repeat. 

C reate an output file containing the current line up to (but not including) the next line of the 
input file that contains a match for regexp. The optional offset is a + or - followed by a positive 
integer. If it is given, the input up to the matching line plus or minus offset is put into the output 
file, and the line after that begins the next section of input. 

Like the previous type except that it dosnot create an output file, so that section of the input file 
is effectively ignored. 

Repeat the previous pattern repeat-count (a positive integer) additional times An asterisk maybe 
given in place of the (integer) repeat count, in which case the preceding pattern isrepeated as many 
times as necessary until theinput isexhausted. 


Theoutput filenames consist of a prefix followed byasuffix. By default, the suffix is merely an ascending linear sequence of 
two-digit decimal numbersstartingwith 00 and ranging up to 99; however, this default may be overridden by either the - 
digits option or by the -suffix-format option. (See "Options," next.) In any case, concatenating the output files in sorted 
order by filename produces the original input file in order. The default output filename prefix isxx. 

By default, if cspiit encounters an error or receives a hangup, interrupt, quit, or terminate signal, it removes any output files 
that it has created so far before it exits. 


OPTIONS 


-b, — suffix-formatesuff i 


-k, -keep-files 

-z, -elide-empty-files 


-s, -q, —silent, —quiet 


— version 


Usepref i x astheoutput filename prefix string. 

Usesuf f i * asthe output filename suffix string. When this option is specified, the suffix string 
must include exactly one printf(3) style conversion specification (such as%d, possibly including 
format specification flags, afield width, a precision specifications, or all of these kinds of 
modifiers). The conversion specification must be suitable for converting a binary integer 
argument to readable form. Thus, only d, i, u, o, x, and x format specifiers are allowed. The 
entire suffix string isgiven (with the current output file number) to sprintf(3) to form the 
filename suffixes for each of the individual output filesin turn. Note that when this option is 
used, the -digits option is ignored. 

Use output filenames containing numbers that are di gits digits long instead of the default 2. 

D o not remove output files when errors are encountered. 

Suppress the generation of zero-length output files. (In cases where the section delimiters of the 
input file are supposed to mark the first lines of each of the sections, thefirst output file will 
generally be a zero-length file unless you usethisoption.) Note that the output file sequence 
numbers will always run consecutively, starting from 0, even in cases where zero-length output 
sections are suppressed due to the use of this option. 

D o not print counts of output file sizes. 

Print a usage message and exit with a nonzero status. 

Print version information on standard output, then exit. 
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ctags 

ctags-Generates tags and (optionally) refs files 

SYNOPSIS 

ctags [ -BSstvraT] f i I esnamcs... 

DESCRIPTION 

ctags generates the tags and refs files from a group of C source files The tags file is used by theeivis :tag command, 
control-] command, and -t option. The refs file is sometimes used by the ref (1) program. 

Each C source file is scanned for #deftne statements and global function definitions The name of the macro or function 
becomes the name of atag. For each tag, a line isadded to the tags filethat containsthefollowing: 

■ The name of the tag 

■ A tab character 

■ The name of the file containing the tag 

■ A tab character 

■ A way to find the particular line within the file 

Thef i i enames list will typically be the names of all C source files in the current directory, like this 
$ ctags -stv *.[ch] 

OPTIONS 

-B N ormally, ctags encloses regular expressions in slashes (/regexp/), which causes eivis to search from the 

top of the file The -b flag causes ctags to enclose theregular expressions in question marks (?regexp?) so 
eivis will search backward from the bottom of the file. Thisrarely matters 
-t Include typedefs. A tag will be generated for each user-defined type Also tags will be generated for struct 

and enum names. Types are considered to be global if they are defined in a header file, and static if they are 
defined in aC sourcefile. 

-v Include variable declarations. A tag will be generated for each variable, except for thosethat are declared 

inside the body of a function. 

-s Include static tags ctags will normally put global tagsin thetags file, and silently ignore the static tags. 

This flag causes both global and static tags to be added. The name of a static tag isgenerated by prefixing 
the name of the declared item with thenameof the file where it is defined, with acolon in between. For 
example, static foo()<} in bar.c results in atag named bar.c:foo. 

-s Include static tags but make them look like global tags. M ost tags-aware programs don't like the 

filename itagname tags produced by the -s flag, so -s was added as an alternative. If eivis and ref are the 
only programsthat read the tags file, then you don't need -s; otherwise you do. 

-r This causes ctags to generate both tags and refs. Without -r, it would only generate tags. 

-a Append to tags, and maybe refs. Normally, ctags overwrites these files each time it is invoked. This flag is 

useful when you have too many files in the current directory for you to list them on a single command 
line; it allows you to split thearguments among several invocations 
-t This flag isn't available on all systems. UN IX has it, but most others don't. The -t flag prevents ctags 

from generating a tags file T his is useful when you want to generate a refs without changing tags. 

FILES 

tags A cross-reference that lists each tag name, the name of the source file that contains it, and a way to locate a 

particular linein the source file 

refs Therefsfilecontainsthedefinitionsforeach tag in the tags file and very little else. This file can be 

useful, for example, when licensing restrictions prevent you from making the source code to the standard 
C library readable by everybody, but you still want everybody to know what arguments the library 
functions need. 



Parti: User Commands 


88 


BUGS 

ctags issensitiveto indenting and line breaks Consequently, it might not discover all of thetagsin afilethat isformatted in 
an unusual way. 

SEE ALSO 

elvis(l), refs(l) 

AUTHOR 

Steve Kirkendall (kinkenda@cs.pdx.edu) 


cu 

cu- Call up another system 

SYNOPSIS 

cu [ options ] [ system | phone | "dir" ] 

DESCRIPTION 

Thecu command is used to call up another system and act as a dial in terminal. It can also do simple file transfers with no 
error checking. 

cu takes a single argument, besides the options. If the argument is the string dir, cu will make a direct connection to the port. 
This may only be used by users with write access to the port, as it permits reprogramming the modem. 

Otherwise, if the argument beginswith a digit, it istaken to be a phone number to call. Otherwise, it istaken to be the name 
of a system to call. The-z or - system option may be used to name a system beginning with a digit, and the-c or - phone 
option may be used to name a phone number that does not begin with a digit. 

cu locates a port to use in the UUCP configuration files. If a simple system nameisgiven, it will select a port appropriate for 
that system. The-p, -port,-i, -line, -s, and -speed options may be used to control the port selection. 

W hen a connection ismadeto the remote system, cu forks into two processes 0 ne reads from the port and writes to the 
terminal, while the other reads from the terminal and writes to the port. 

cu provides several commands that may be used during the conversation. The commands all begin with an escape character, 
initially' (tilde). T he escape character isonly recognized at the beginning of a line. T o send an escape character to the 
remote system at the start of a line it must be entered twice All commands are either a single character or aword beginning 
with % (percent sign), 
cu recognizesthefollowing commands 

Terminatetheconversation. 

'! command Run command in a shell. If command isempty, starts up a shell. 

■$ command Run command, sending the standard output to the remote system. 

'! command Run command, taking thestandard input from the remote system. 

'+ command Run command, taking thestandard input from the remote system and sending the standard 

output to the remote system. 

'#, '%br eak Send a break signal, if possible. 

'c di rectory, -%cd directory Change the local directory. 

"> file Send a file to the remote system. This just dumps the file over the communication line It is 

assumed that the remote system is expecting it. 

•< Receiveafilefrom the remote system. This promptsfor the local filename and for the 

remote command to execute to begin the file transfer. It continues accepting data until the 
contents of the eof read variable are seen. 






to, '%put from to 


%nostop 


delay 

eol 

binary-prefix 


timeout 

kill 

resend 

eofread 

verbose 
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Send afileto a remoteU NIX system. This runsthe appropriate commandson the remote 
system. 

RetrieveafilefromaremoteUN IX system. This runs the appropriate commands on the 
remote system. 

Sdtacu variable to the given value. If vai ue isnotgiven,thevariableissdttoTrue. 

Sdtacu variable to False. 

Suspend thecu session. This is only supported on some systems On systems for which "z 
may be used to suspend a job, "z will also suspend the session. 

Turn off xon/xoff handling. 

Turn on xon/xoff handling. 

List all the variables and their values 
List all commands 

cu also supports several variables. They may be listed with the ‘v command, and sdt with the 
‘s or'! commands. 

The escape character. Initially ■ (tilde). 

If this variable is True, cu will delay for a second after recognizing the escape character before 
printing the name of the local system. The default isTrue. 

The list of characters which are considered to finish aline. The escape character is only 
recognized after oneof theseisseen. The default is carriage return, "u, “c, 'o, 'd, "s, "q, *r. 

W hether to transfer binary data when sending a file. If this is False, then newlines in the file 
being sent are converted to carriage returns The default israise. 

A string used before sending a binary character in a file transfer, if the binary variable is 
True. The default is *z. 

W hether to check filetransfers by examining what the remote system echoes back. This 
probably doesn't work very well. T he default is False. 

The character to look for after sending each line in a file The default is carriage return. 

The timeout to use, in seconds when looking for a character, either when doing echo 
checking or when looking for the echom character. The default is 30 . 

The character to use to delete a line if the echo check fails The default is “u. 

The number of times to resend a line if the echo check continues to fa'I. Thedefault isie. 
The string to write after sending a file with the ■> command. Thedefault is "d. 

The string to look for when receiving a file with the '< command. Thedefault is $, which is 
intended to be a typical shell prompt. 

Whether to print accumulated information during a file transfer. Thedefault isTrue. 


OPTIONS 


Thefollowing options may be given to cu: 


-e, -parity=even 

-h, —halfduplex 
-z system, —system system 
-c phone-number, —phone phone-number 
-p port, -port port 


Use even parity. 

U se odd parity. 

U se no parity. N 0 parity is also used if both -e and -0 are given. 

Echo characters locally (half-duplex mode). 

The system to call. 

The phone number to call. 

N ame the port to use. 

Equivalents -port port. 

N ame the line to use by giving a device name This may be used to dial out on 
ports that are not listed in the U U C P configuration files Write access to the device 
is required. 
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-s speed, -speed speed 
-n, -prompt 


-x type, -debug type 


-I file, —config file 




The speed (baud rate) to use. 

Where# is a number, equivalent to -speed #. 

Prompt for the phone number to use. 

Enter debugging mode. Equivalent to -debug ail. 

T urn on particular debugging types. The following types are recognized: abnormal, 
chat, handshake, uucpproto, proto, port, config, spooldir, execute, incoming, 
outgoing. 0 nly abnormal, chat, handshake, port, config, incoming and outgoing are 

meaningful for cu. M ultiple types may be given, separated by commas, and the - 
debug option may appear multi pletimes. A number may also be given, which will 
turn on that many types from theforegoing list; for example, -debug 2 is 
equivalent to -debug abnormal,chat, -debug aii may be used to turn on all 
debugging options 

set configuration file to use This option may not be available depending upon 
howcu was compiled. 

Report version information and exit. 

Print a help message and exit. 


BUGS 

This program does not work very welI. 

FILES 

Thefilenamemay be changed at compilation time so thisisonly an approximation. Configuration file 

/usr/lib/uucp/config 


AUTHOR 

Ian Lance Taylor (ian@airs.com) 


Taylor UUCP 1.05 


cut 

cut- Removesectionsfrom each lineof files 

SYNOPSIS 

cut -{-b byte-list, — bytes=byt e-I i st} [-n] [ — help] [—version] [file...] 

cut ]-c character-list, -characters=char act er -1 i st} [-help] [-version] [file...] 

cut {-f field-list, —fields=f i el d -1 i st } [-d del i m] [-s] [—delimiter=de I i m] 

[-only-delimited] [-help] [-version] [file...] 

DESCRIPTION 

This manual page documents the GN U version of cut. cut prints sections of each lineof each input file, or the standard 
input if no files are given. A filename of - means standard input. The sections to be printed are selected by the options 

OPTIONS 

The byte-1 ist, character-1 i st, and field-list options are one or more numbers or ranges (two numbers separated by a 
dash) separated by commas T hefirst byte, character, and field are numbered 1.1 ncomplete ranges may be given: -m means 1- 
m; n- means n through end of lineor last field. 





-b, -bytes byte -1 i st 


-c, —characters character -1 i st 


-f, -fields f i el d -1 i $| 
-d, —delimiter del i m 

-s, -only-delimited 

— version 


Print only the bytes in positions listed in byte-1 i st . Tabs and backspaces are treated like 
any other character; they take up one byte 

Print only characters in positions listed in character -1 1 st. The same as-b for now, but 
internationalization will change that. Tabs and backspaces are treated like any other 
character; they take up one character. 

Print only thefields listed in f i ei d-1 i st . Fields are separated by tab by default. 

For -f, fields are separated by the first character in del i m instead of by tab. 

Do not split multibyte characters (no-op for now). 

For -f, do not print lines that do not contain the field separator character. 

Print a usage message and exit with a nonzero status. 

Print version information on standard output then exit. 
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cvs- C oncurrent V ersions System 

SYNOPSIS 

cvs [ cvs_options ] cvs-command [ command_options ][command_args ] 


DESCRIPTION 

cvs isa front end to the rcs(l) revision control system, which extends the notion of revision control from a collection of files 
in a single directory to a hierarchical collection of directories consisting of revision controlled files. T hese directories and files 
can be combined together to form a software release, cvs provides the functions necessary to manage these software releases 
and to control the concurrent editing of source files among multiple software developers 

cvs keeps a single copy of the master sources. This copy is called the source repository, it contains all the information to 
permit extracting previous software releases at any time based on either a symbolic revision tag, or a date in the past. 


ESSENTIAL COMMANDS 


cvs provides a rich variety of commands (cvs_command in the Synopsis), each of which often has a wealth of options, to satisfy 
the many needs of source management in distributed environments. However, you don't have to master every detail to do 
useful work with cvs; in fact, five commands are sufficient to use (and contribute to) the source repository. 


cvs checkout modul es.. 


cvs update 


cvs remove file. 




A necessary preliminary for most cvs work: creates your private copy of the source for 
modules (named collections of source; you can also use a path relative to the source 
repository here). You can work with thiscopy without interfering with others' work. At 
least one subdirectory level is always created. 

Execute thiscommand from within your private source directory when you wish to 
update your copies of source files from changes that other developers have made to the 
source in the repository. 

Use this command to enroll new files in cvs records of your working directory. The files 
will be added to the repository the next time you run cvs commit. Note: You should use 
the cvs import command to bootstrap new sources into the source repository, cvs add is 
only used for new files to an already checked-out module. 

Use this command (after erasing any files listed) to declare that you wish to eliminate 
files from the repository. The removal does not affect others until you run cvs commit. 
Use this command when you wish to "publish" your changes to other developers, by 
incorporating them in the source repository. 
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FI 


OPTIONS 

The cvs command line can include cvs_options, which apply to the overall cvs program; a cvs_command, which specifies a 
particular action on the Source repository; and commandjjptions and command_arguments to fully Specify What the cvs_cominand 
will do. 


WARNING 


You must be careful of precisely where you place options relative to the cvs_command. The same option can mean different 
things depending on whether it is in thecvs_options position (to the left of a cvs command) or in the command_options 
position (to the right of a cvs command). 


There are only two situations where you may omit cvs_comniand: cvs -Hor cvs -help elicits a list of available commands, and 
cvs -v or cvs -version displays version information on cvs itself. 


CVS OPTIONS 


As of release 1.6, cvs supports GNU style long options as well as short options 0 nly a few long options are currently 
supported; these are listed in brackets after the short options whose functions they duplicate. 


Use these options to control the overall cvs program: 


-H [-help] 


-v [-version] 




D isplay usage information about the specified cvs command (but do not actually execute the 
command). If you don't specify a command name, cvs -h displays a summary of all the 
commands available 

Causes the command to be really quiet; the command will generate output only for serious 
problems 

Causes the command to be somewhat quiet; informational messages, such as reports of 
recursion through subdirectories are suppressed. 

Usebi ndi r as the directory where RC 5 programsare located. 0 verridesthe setting of the rcsbin 
environment variable. This value should be specified as an absolute pathname 
Usecvs.root.di rectory asthe root directory pathnameof the master RC S source repository. 

0 verridesthe setting of the cvs-root environment variable This value should be specified as an 
absolute pathname. 

U se e d i t o r to enter revision log information. 0 verrides the setting of the cvseditor and the 

editor environment variables 

Do not read the cvs startup file ("/.cvsrc). 

Do notlogthecvs_cominanci in the command history (but execute it anyway). See the descrip¬ 
tion of the history command for information on command history. 

D o not change any files. Attempt to execute the cvs_command, but only to issue reports do 
not remove update, or merge any existing files or create any new files 
T race program execution; display messages showing the steps of cvs activity. Particularly useful 
with -n to explore the potential impact of an unfamiliar command. 

M akesnew working files read-only. Same effect asif thecvs-READ environment variable isset. 
Displays version and copyright information for cvs. 

M akesnew working files read-write (default). Overrides thesetting of the cvsread environment 
variable 

When transferring files across the network use gzip with compression level compressi on-i evei to 
compress and decompress data as it is transferred. Requires the presence of theGN U gzip 
program in the current search path at both ends of the link. 



USAGE 

Except when requesting general help with cvs -h, you must specify a cvs_command to cvs to select a specific release control 
function to perform. Each cvs command accepts its own collection of options and arguments H owa/er, many options are 
available across several commands. You can display a usage summary for each command by specifying the -h option with the 
command. 

CVS STARTUP FILE 

Normally, when cvs starts up, it reads the .cvsrc file from the home directory of the user reading it. This startup procedure 
can be turned off with the -f flag. 

The .cvsrc file lists cvs commands with a list of arguments, one command per line. For example, the following line in 
diff -c 

will mean that the cvs diff command will always be passed the-c option in addition to any other options that are specified 
in the command line (in this case, it will have the effect of producing context sensitive diffs for all executions of cvs diff). 

CVSCOMMAND SUMMARY 

H ere are brief descriptions of all the cvs commands 

add Add a new file or directory to the repository, pending a cvs commit on the same file. Can only be done 

from within sources created by a previous cvs checkout invocation. Use cvs import to place whole new 
hierarchies of sources under cvs control. (Does not directly affect repository; changes working 
directory.) 

admin Execute RC S control functions on the source repository. (Changes repository directly; uses working 

directory without changing it.) 

checkout M ake a working directory of source files for editing. (C reates or changes working directory.) 

commit Apply to the source repository changes, additions, and deletions from your working directory. 

(C hanges repository.) 

diff Show differences between files in working directory and source repository, or between two revisions in 

source repository. (D oes not change either repository or working directory.) 
export Prepare copies of asetof sourcefilesforshipmentoff site. Differs from cvs checkout in that no cvs 

admi nistrati ve directoriesare created (and therefore cvs commit cannot beexecuted from a directory 
prepared with cvs export), and a symbolic tag must be specified. (D oes not change repository; creates 
directory similar to working directories). 

history Show reports on cvs commands that you or others have executed on a particular file or directory in the 

source repository. (D oes not change repository or working directory.) H istory logs are kept only if 
enabled by creation of the$cvsR00T/cvsR00T/history file; seecvs(5). 
import Incorporate a set of updates from off-site into the source repository, as a "vendor branch." (Changes 

repository.) 

log D isplay RC S log information. (Does not change repository or working directory.) 

rdiff Prepare a collection of diffs asapatch file between two releases in the repository. (Does not change 

repository or working directory.) 

release Cancel a cvs checkout, abandoning any changes (Can delete working directory; no effect on 

repository.) 

remove Remove files from the source repository, pending a cvs commit on the same files (Does not directly 

affect repository; changes working directory.) 

rtag Explicitly specify a symbolic tag for particular revisions of files in the source repository. See also cvs 

tag. (Changes repository directly; does not require or affect working directory.) 
status Show current statusof files latest version, version in working directory, whether working version has 

been edited and, optionally, symbolic tags in theRCS file (Does not change repository or working 
directory.) 
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Specify a symbolic tag for files in the repository. By default, tags the re/isionsthat were last synchro¬ 
nized with your working directory. (Changes repository directly; uses working directory without 
changing it.) 

Bring your working directory up to date with changes from the repository. M erges are performed 
automatically when possible; a warning is issued if manual resolution is required for conflicting 
changes (C hanges working directory; does not change repository.) 

COMMON COMMAND OPTIONS 

This section describes the command_options that are available across several cvs commands N ot all commands support all of 
these options each option is only supported for commands where it makes sense. However, when a command has one of 
these options you can counton the same meaning for the option as in other commands (Other command options, which 
are listed with the individual commands may have different meanings from onecvs command to another.) 


update 


WARNING 


The history command isan exception; it supports many optionsthat conflict even with these standard options 


-d date Use the most recent revision no later than date_spec (a single argument, date description specifying a 

date in the past). A wide variety of date formats are supported by the underlying RC 5 facilities similar 
to those described in co(l), but not exactly the same. The date_spec is interpreted as being in the local 
time zone, unless a specific time zone is specified. The specification is "sticky" when you use it to make 
a private copy of a source file: that is when you get a working file using -d, cvs records the date you 
specified, so that further updates in the same directory will use the same date (unless you explicitly 
override it; see the description of the update command), -d is available with thecheckout, diff, history, 
export, rdiff, rtag, and update commands Examples of valid date specifications include the following: 

1 month ago 

2 hours ago 
400000 seconds ago 
last year 

last M onday 
yesterday 
a fortnight ago 
3/31/92 10:00:07 PST 
January 23,1987 10:05pm 
22:00 GMT 

-t When you specify a particular date or tag to cvs commands, they normally ignore files that do not 

contain the tag (or did not exist on the date) that you specified. Use the -f option if you want files 
retrieved even when there is no match forthetagordate (The most recent version isused in this 
situation.) -f is available with these commands checkout, export, rdiff, rtag, and update. 

-h Help; describetheoptionsavailableforthiscommand. This istheonly option supported for all cvs 

commands 

-k kfi ag Alter the default RCS processing of keywords all the -k options described in co(l) are available The-k 

option is available with the add, checkout, diff, export, rdiff, and update commands Your kf i ag 
specification is "sticky" when you use it to create a private copy of a source file that is, when you use 
thisoption with thecheckout or update commands, cvs associates your selected kf i ag with thefile and 
continues to use it with future update commands on the same file until you specify otherwise 
Someof the more useful kfi agsare-ko and -kb (for binary files, only compatible with RCSversion 5.7 
or later), and -kv, which is useful for an export where you wish to retain keyword information after an 
import at some other site. 



Local; run only in current working directory, rather than recurring through subdirectories. Available 
with thefollowing commands: checkout, commit, diff, export, remove, rdiff, rtag, status, tag, and 
update. 


WARNING 


This is not the same as the overall cvs -1 option, which you can specify to the left of a cvs command. 


Do not run any checkout/commit/tag/update program. (A program can be specified to run on each of 
these activities, in the modules database; thisoption bypassesit.) Available with the checkout, commit, 
export, and rtag commands 


WARNING 


This is not the same as the overall cvs -n option, which you can specify to the left of a cvs command. 


-p Prune (remove) directories that are empty after being updated, on checkout, or update. N ormally, an 

empty directory (one that is void of revision-controlled files) is left alone Specifying -p will cause these 
directories to be silently removed from your checked-out sources Thisdoesnot remove the directory 
from the repository, only from your checked out copy. N ote that this option is implied by the -r or -d 
options of checkout and export. 

-p Pipe the files retrieved from the repository to standard output, rather than writing them in the current 

directory. Available with the checkout and update commands 

-r tag Use the revision specified by thetag argument instead of the default head revision. As well as arbitrary 

tags defined with the tag or rtag command, two special tags are always available: head refers to the 
most recent version available in the repository, and base refers to the revision you last checked out into 
the current working directory. Thetag specification is "sticky" when you use this option with cvs 
checkout or cvs update to makeyourown copy of a file cvs remembers the tag and continues to use it 
on future update commands, until you specify otherwise, tag can be either a symbolic or numeric tag, 
in RCS fashion. Specifying the -q global option along with the-r command option isoften useful, to 
suppress the warning messageswhen the RCS file does not contain the specified tag. -r is available 
with the checkout, commit, diff, history, export, rdiff, rtag, and update commands. 


WARNING 


This is not the same as the overall cvs -r option, which you can specify to the left of a cvs command. 


CVS COMMANDS 

H ere (finally) are details on all the cvs commands and the options each accepts T he summary lines at the top of each 

command's description highlight three kindsof things 

Command Optionsand Arguments Special options are described in detail; common command options may appear only 
in thesummary line 

W orking D irectory, or Repository? Some cvs commands require a working directory to operate; some require a 

repository. Also, some commands change the repository, some change the working 
directory, and some change nothing. 

Synonyms M any commands have synonyms which you may find easier to remember (or type) 

than the principal name 
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■ add [-k k f I a g][-m 'message'] files... 

Requires Repository, working directory 

Changes Working directory 

Synonym: new 

U se the add command to create a new file or directory in the RC S source repository. T he files or directories specified with 
add must already exist in the current directory (which must have been created with the checkout command). To add a whole 
new directory hierarchy to the source repository (for example, files received from a third-party vendor), use the cvs import 
command instead. 

If the argument to cvs add refers to an immediate subdirectory, thedirectory iscreated at thecorrect place in the RCS source 
repository, and the necessary cvs administration files are created in your working directory. If thedirectory already exists in 
the source repository, cvs add still creates the administration filesin your version of thedirectory. This allows you to use cvs 
add to add a particular directory to your private sources even if someone else created that directory after your checkout of the 
sources You can do thefollowing: 

example% mkdir new_directory 
example% cvs add new_directory 
example% cvs update new_directory 

An alternate approach using cvs update might be: 
example% cvs update -d new_directory 

(To add any available new directoriesto your working directory, it's probably simpler to use cvs checkout or cvs update -d.) 
The added files are not placed in the RCS source repository until you use cvs commit to make the change permanent. Doing 
acvs add on a file that was removed with the cvs remove command will resurrect thefile, if no cvs commit command 
intervened. 

You will have the opportunity to specify a logging message, as usual, when you use cvs commit to make the new file 
permanent. If you'd like to have another logging message associated with just creation of the file (for example, to describe the 
file's purpose), you can specify it with the-m message option to the add command. 

The -k kf i ag option specifies thedefault way that thisfile will be checked out. Thekf i ag argument isstored in theRCSfile 
and can be changed with cvs admin. Specifying -ko is useful for checking in binaries that shouldn't havetheRCSid strings 
expanded. 

■ admin [res-opt ions] files... 

Requires Repository, working directory 

Changes Repository 

Synonym: res 

This isthe cvs interface to assorted administrative RCS facilities documented in rcs(l). cvs admin simply passes all its 
optionsand arguments to the res command; it does no filtering or other processing. This command does work recursively, 
however, so extreme care should be used. 

■ checkout [options] modules... 

Requires Repository 

Changes Working directory 

Synonyms co, get 

M ake a working directory containing copies of the source files specified by modules You must execute cvs checkout before 
using most of the other cvs commands since most of them operate on your working directory, 
mo d u i e s are either symbolic names [themselves defined as the module modules i n the source repository; see cvs(5)] for some 
collection of source directories and files, or paths to directories or files in the repository. 

Depending on the modules you specify, checkout may recursively create directories and populate them with the appropriate 
source files You can then edit these source files at anytime (regardless of whether other software developers are editing their 




own copies of the sources); update them to include new changes applied by others to thesource repository; or commit your 
work as a permanent change to the RC S repository. 

N ote that checkout is used to create directories. T he top-level directory created is always added to the directory where 
checkout is invoked, and usually has the same name as the specified module. In the case of a module alias, the created 
subdirectory may have a different name, but you can be sure that it will be a subdirectory, and that checkout will show the 
relative path leading to each file asit is extracted into your private work area (unless you specify the -a global option). 
Running cvs checkout on a directory that wasalready built by a prior checkout isalso permitted, and has the same effect as 
specifying the-d option to the update command described later. 

The options permitted with cvs checkout include the standard command options-p, -f, -k ktiag, - 1 , -n, -p, -rtag, and -d 
date In addition to those you can use several special command options with checkout, as detailed in the following para¬ 
graphs. 

U se the -a option to reset any sticky tags, dates, or -k options. (If you get a working file using one of the -r, -d, or -k 
options, cvs remembers the corresponding tag, date, orkfiag and continues using it on future updates; use the -a option to 
make cvs forgdt these specifications, and retrieve the head version of the file). 

The-j branch option merges the changes made between the resulting revision and the revision that it isbased on (for 
example, if thetag refers to a branch, cvs will merge all changes made in that branch into your working file). 

With two -j options, cvs will merge in the changes between thetwo respective revisions. This can be used to "remove" a 
certain delta from your working file. 

In addition, each -j option can contain on optional date specification which, when used with branches, can limit the chosen 
revision to one within a specific date An optional date is specified by adding a colon (:) to thetag. An example might be 
what cvs import tellsyou to do when you havejust imported sources that have conflicts with local changes; 
example% cvs checkout -jTAG:yesterday -jTAG module 

U se the -n option with -d dir to avoid shortening module paths in your working directory. (N ormally, cvs shortens paths as 
much as possible when you specify an explicit target directory.) 

U se the -c option to copy the module file, sorted, to the standard output, instead of creating or modifying any files or 
directories in your working directory. 

Usethe-d dir option to create a directory called di r for the working files, instead of using the module name Unless you 
also use -n, the paths created under dir will be as short as possible 

Use the-s option to display per-module status information stored with the-s option within the modules file. 

■ commit [-lnR][-m 1 logjnessage' | -f file][-r revision][fiIes ...] 

Requires: Workingdirectory, repository 

Changes Repository 

Synonym: ci 

Use cvs commit when you want to incorporate changesfrom your working source files into thegeneral source repository. 

If you don't specify particular files to commit, all of the files in your working current directory are examined, commit is 
careful to change in the repository only those files that you have really changed. By default (or if you explicitly specify the - r 
option), filesin subdirectories are also examined and committed if they have changed; you can usethe-i option to limit 
commit to thecurrent directory only. Sometimes you may wanttoforceafileto be committed even though it is unchanged; 
this is achieved with the-f flag, which also has the effect of disabling recursion (you can turn it back on with -r, of course), 
commit verifies that the selected files are up-to-date with thecurrent revisions in the source repository; it will notify you, and 
exit without committing, if any of the specified files must be made current first with cvs update, commit does not call the 
update command for you, but rather I eaves that for you to do when thetime is right. 

When all is well, an editor is invoked to allow you to enter a log message that will be written to one or more logging 
programs and placed in the RC S source repository file You can instead specify the log message on the command line with 
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the -m option, thus suppressing the editor invocation, or use the -f option to specify that the argument file contains the log 
message. 

The -r option can be used to commit to a particular symbolic or numeric revision within the RCS file. For example to bring 
all your files up to the RCS revision 3.0 (including those that haven't changed), you might use 
example% cvs commit -r3.0 

cvs will only allow you to commit to a revision that is on the main trunk (a revision with a single dot). H owever, you can 
also commit to a branch revision (one that has an even number of dots) with the -r option. To create a branch revision, one 
typically use the -b option of the rtag or tag commands. T hen, either checkout or update can be used to base your sources on 
the newly created branch. From that point on, all commit changes made within these working sources will be automatically 
added to a branch revision, thereby not perturbing mainline development in any way. For example, if you had to create a 
patch to the 1.2 version of the product, even though the 2.0 version is already under development, you might use this: 

example% cvs rtag -b -rFCS1_2 FCS1_2 Patch productjnodule 
example% cvs checkout -rFCS1_2_Patch product module 
example% cd product module 
[[ hack away ]] 
example% cvs commit 

Say you have been working on some extremely experimental software, based on whatever revision you happened to checkout 
last week. If others in your group would like to work on this software with you, but without disturbing mainline develop¬ 
ment, you could commit your change to a new branch. Others can then check out your experimental stuff and utilize thefull 
benefit of cvs conflict resolution. The scenario might look like this 

example% cvs tag -b EXPR1 
example% cvs update -rEXPRI 
[[ hack away ]] 
example% cvs commit 

Others would simply do cvs checkout -texpri whate«er_modui e to work with you on the experimental change. 

■ diff [-kl][rcsdi f f_opt i ons][[-r r ev1 | -D datel][-r rev2 | -D d a t e 2]] [files...] 

Requires W orking directory, repository 

Changes Nothing 

You can compare your working files with revisionsin the source repository, with the cvs diff command. If you don't specify 
a particular revision, your files are compared with the revisions they were based on. You can also use the standard cvs 
command option -r to specify a particular revision to compare your files with. Finally, if you use -r twice, you can see 
differences between two revisionsin the repository. You can also specify -d options to diff against a revision in the past. The 
-r and -d options can be mixed together with at most two options ever specified. 

See rcsdiff(l) for a list of other accepted options 

If you don't specify any files, diff will display differences for all those files in the current directory (and its subdirectories, 
unless you use the standard option - 1 ) that differ from the corresponding revision in the source repository (that is, files that 
you have changed), or that differ from the revision specified. 

■ export [-f INnQq] -r re* ] -D date [-d dir][-k kflag] module... 

Requires Repository 

C hanges C urrent directory 

This command is a variant of cvs checkout; use it when you want a copy of the source for modui e without the cvs administra¬ 
tive directories For example, you might use cvs export to prepare source for shipment off-site. Thiscommand requires that 
you specify a date or tag (with -Dor -r), so that you can counton reproducingthesourceyoushipto others 
Theonly nonstandard options are -d dir (write the source into directory di r) and -n (don't shorten module paths). These 
have the same meanings as the same options in cvs checkout. 




The-kv option is useful when export is used. T his causes any RCS keywords to be expanded such that an import done at 
some other site will not lose the keyword revision information. Other kf i ag options may be used with cvs export and are 
described in co(l). 

■ history [-report][-f I ags][-opt i ons ar gs ] [f i I es ... ] 

Requi res: T he fi le $cvsROOT/cvsROOT/history 

Changes: Nothing 

cvs keeps a history file that tracks each use of the checkout, commit, rtag, update, and release commands. You can use cvs 
history to display this information in various formats. 


WARNING 


cvs history uses-f, -l, -n, and -p in ways that conflict with the descriptions in "Common Command Options," earlier 
in this manual page. 


Several options (shown as [-report ] in the preceding bulleted code line) control what kind of report isgenerated: 

-c Report on each time commit was used (that is, each timethe repository wasmodified). 

-m modui e Report on a particular module. (You can meaningfully use-m more than onceon the command line.) 

-o Report on checked-out modules. 

-t Report on all tags. 

-x type Extract a particular set of record types x from the cvs history. The types are indicated by single letters, 

which you may specify in combination. Certain commands have a single record type: check-out (type 
o), release (type f), and rtag (type t). 0 ne of four record types may result from an update: w, when the 
working copy of a file isdeleted during update (because it was gone from the repository); u, when a 
working file was copied from the repository; g, when a merge was necessary and it succeeded; andc, 
when a merge was necessary but collisions were detected (requiring manual merging). Finally, one of 
three record types results from commit: m, when a file was modified; a, when a file is first added; and r, 
when a file is removed. 

-e Everything (all record types); equivalent to specifying -xmacfrogwut. 

-z zone Use time zonez one when outputting history records. ThezonenameLT standsfor local time; numeric 

offsets stand for hours and minutes ahead of UTC. For example, +0530 standsfor 5 hours and 30 
mi nutes ahead of (that is, east of) U T C. 

The options shown as-f 1 ags constrain the report without requiring option arguments: 

-a Show data for all users. (The default is to show data only for the user executing cvs history.) 

-1 Show last modification only. 

-w Show only the records for modifications done from the same working directory where cvs history is 

executing. 

The options shown as-opti ons ar gs constrain the report based on an argument: 

Show data back to a record containing the string str in either the module name, thefilename, or the 
repository path. 

Show data sincedate. 

Show data for a particular source repository (you can specify several -p options on the same command 
line). 

Show records referring to revisions since the revision or tag named rev appears in individual RCS files. 
Each RCS file is searched for the revision or tag. 

Show records si nee tag t a g was last added to the history fi le. T his differs from the - r flag in that it 
reads only the history file, not the RC S files, and is much faster. 

Show records for username. 
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Requires Repository, source distribution directory 

Changes Repository 

U se cvs import to incorporate an entire source distribution from an outside source (for example, a source vendor) into your 
source repository directory. You can use this command both for initial creation of a repository, and for wholesale updates to 
the module form the outside source. 

The repository argument gives a directory name (or a path to a directory) under the CVS root directory for repositories if 
the directory did not exist, import creates it. 

When you use import for updates to source that has been modified in your source repository (since a prior import), it will 
notify you of any filesthat conflict in the two branches of development; use cvs checkout -j to reconcile the differences, as 
import instructs you to do. 

Bydefault, certain filenames are ignored during cvs import: names associated with CVS administration, or with other 
common source control systems; common names for patch files, object files, archive files, and editor backup files; and other 
names that are usually artifacts of assorted utilities. C urrently, the default list of ignored files includes files matching these 
names: 

RCSLOG RCS SCCS 
CVS* cvslog.* 
tags TAGS 

.make.state .nse_depinfo 


.old *.bak *.BAK *.orig *.rej .del-* 

.a *.o *.so *.Z *.elc *.ln core 

The outside source is saved in a first-level RCS branch, by default 1 . 1 . 1 . Updates are leaves of this branch; for example, files 
from the first imported collection of source will be revision 1 . 1 . 1 . 1 , then files from the first imported update will be revision 
1 . 1 . 1 . 2 , and so on. 

At least three arguments are required, repository is needed to identify the collection of source, vendor tag is a tag for the 
entire branch (for example, for 1 . 1 . 1 ). You must also specify at least oner e easetag to identify the files at the leaves created 
each time you execute cvs import. 

One of the standard cvs command options is available: -m message. If you do not specify a logging message with -m, your 
editor is invoked (aswith commit) to allow you to enter one 
There are three additional special options 

Use-d to specify that each file's time of last modification should be used forthecheckin date and time. 

U se -b branch to specify a first-level branch other than 1 . 1 . 1 . 

Use -1 name to specify filenames that should be ignored during import. You can usethisoption repeatedly. To avoid 
ignoring anyfiles at all (even those ignored by default), specify -1 i. 

■ log [-1] r I og-opt i ons [files...] 

Requires: Repository, working directory 

Changes Nothing 

Synonym: riog 

Display log information for t i 1 es. cvs log calls the RCS utility riog; all the options described in riog(l) are available 
Among the more useful riog optionsare -h to display only the header (including tag definitions, but omitting most of the 
full log); -r to select logs on particular revisions or ranges of revisions and -d to select particular dates or date ranges. See 
nog(l) for full explanations. This command is recursive by default, unless the -1 option isspecified. 
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■ rdiff [-flags] [-V vn][-r t |-D d [-r t2| -D d2]] modules... 

Requires: Repository 

Changes: Nothing 

Synonym: patch 

Buildsa Larry Wall format patch(l) file between two releases that can be fed directly into the patch program to bring an old 
release up-to-date with the new release (This isone of thefew cvs commands that operatesdirectly from the repository and 
doesn't require a prior checkout.) T he diff output is sent to the standard output device You can specify (using the standard 
-r and -d options) any combination of one or two revisions or dates. If only one revision or date is specified, the patch file 
reflects differences between that revision or date and the current head revisions in the RC S file 
Note that if the software release affected is contained in more than one directory, then it may be necessary to specify the-p 
option to the patch command when patching the old sources, so that patch is able to find the files that are located in other 
directories. 

If you use the option -v »n, RCS keywords are expanded according to the rules current in RCS version vn (the expansion 
format changed with RC S version 5). 

The standard option flags -f and -1 are available with this command. There are also several special optionsf lags. 

If you use the -s option, no patch output is produced. I nstead, a summary of the changed or added files between the two 
releases is sent to the standard output device. This is useful for finding out, for example, which files have changed between 
two dates or revisions. 

If you use the-t option, a diff of the top two revisions is sent to the standard output device. This is most useful for seeing 
what the last change to a fi le was 

If you use the -u option, the patch output uses the newer jntdiff format for context dif f s 

You can use-c to explicitly specify the diff-c form of context difts (which is the default), if you like 

■ release [-dQq] modul es ... 

Requires Working directory 

Changes Working directory, history log 

This command is meant to safely cancel the effect of cvs checkout. Since cvs doesn't lock files it isn't strictly necessary to use 
thiscommand. You can always simply delete your working directory, if you like but you risk losing changes you may have 
forgotten, and you leave no trace in the cvs history file that you've abandoned your checkout. 

Use cvs release to avoid these problems Thiscommand checks that no uncommitted changes are present; that you are 
executing it from immediately above or inside, a cvs working directory; and that the repository recorded for your files is the 
same as the repository defined in the module database. 

If all these conditions are true, cvs release leaves a record of its execution (attesting to your intentionally abandoning your 
checkout) in the cvs history log. 

You can use the -d flag to request that your working copies of the source files be deleted if the release succeeds. 

■ remove [-1R][files...] 

Requires: Working directory 

Changes: Working directory 

Synonyms ™, delete 

Use this command to declare that you wish to remove files from the source repository. Like most cvs commands, cvs remove 
works on files in your working directory, not directly on the repository. As a safeguard, it also requires that you first erase the 
specified files from your working directory. 

Thefilesare not actually removed until you apply your changes to the repository with commit; at that point, the correspond¬ 
ing RCS files in the source repository are moved into the Attic directory (also within the source repository). 
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This command is recursive by default, scheduling all physically removed files that it finds for removal by the next commit. U se 
the-i option to avoid this recursion, or just specify that actual files that you wish remove to consider. 

■ rtag [-f alnRQq] [ -b] [-d ] [-r tag | -Ddate] symbolic_tag modules... 

Requires: Repository 

Changes: Repository 

Synonym: rfreeze 

You can use this command to assign symbolic tags to particular, explicitly specified source versions in the repository, cvs 
rtag works directly on the repository contents (and requires no prior checkout). Use cvs tag instead, to base the selection of 
versions to tag on the contents of your working directory. 

In general, tags (often the symbolic names of software distributions) should not be removed, but the-d option isavailableas 
a means to remove completely obsolete symbolic names if necessary (as might be the case for an Alpha release, say), 
cvs rtag will not movea tag that already exists. W ith the -f option, however, cvs rtag will relocate any instance of 
symbolictag that already exists on that file to the new repository versions. Without the -f option, attempting to use cvs 
rtag to apply a tag that already exists on that file will produce an error message. 

The -b option makes the tag a branch tag, allowing concurrent, isolated development. Thisismost useful for creating a patch 
to a previously released software distribution. 

You can use the standard -r and -Doptionsto tag only those files that already contain acertain tag. This method would be 
used to rename a tag: tag only the files identified by the old tag, then delete the old tag, leaving the new tag on exactly the 
same files as the old tag. 

rtag executes recursively by default, tagging all subdirectories of modules you specify in the argument. You can restrict its 
operation to top-level directories with the standard -1 option; or you can explicitly request recursion with -r. 

The modules database can specify a program to execute whenever a tag is specified; a typical useisto send electronic mail to 
a group of interested parties If you want to bypass that program, use the standard -n option. 

Use the-a option to have rtag look in the Attic for removed files that contain the specified tag. The tag is removed from 
these files which makes it convenient to reuse a symbolic tag as development continues (and files get removed from the 
upcoming distribution). 

■ status [-lRqQ][-v] [files ...] 

Requires W orking directory, repository 

Changes Nothing 

Display a brief report on the current status of files with respect to the source repository, including any sticky tags, dates or-k 
options (Sticky options will restrict how cvs update operates until you reset them; see the description of cvs update -a.... 
You can also use this command to anticipate the potential impact of a cvs update on your working source directory. If you 
do not specify any files explicitly, reports are shown for all files that cvs has placed in your working directory. You can limit 
the scope of this search to the current directory itself (not its subdirectories) with the standard -1 option flag; or you can 
explicitly request recursive status reports with the-R option. 

The-v option causes thesymbolic tags for the RC S file to be displayed as well. 

■ tag [-lQqR][-F][-b][-d][-r tag | -D date] [-f] symbolic_tag [files ...] 

Requires W orking directory, repository 

Changes Repository 

Synonym: freeze 

U se this command to assign symbolic tags to the nearest repository versions to your working sources. The tags are applied 
immediately to the repository, as with rtag. 0 ne use for tags is to record a "snapshot" of the current sources when the 
software freeze date of a project arrives As bugs are fixed after the freeze date, only those changed sources that are to be part 
of the release need be retagged. 



The symbolic tags are meant to permanently record which revisions of which files were used in creating a software distribu¬ 
tion. The checkout, export, and update commands allow you to extract an exact copy of a tagged release at any time in the 
future regardless of whether files have been changed, added, or removed si nee the release was tagged. 

You can use the standard -r and -Doptionsto tag only those files that already contain a certain tag. This method would be 
used to rename a tag: tag only thefiles identified by the old tag, then delete the old tag, leaving the new tag on exactly the 
same files as the old tag. 

Specifying the -f flag in addition to the-r or -d flags will tag those files named on thecommand line even if they do not 
contain the old tag or did not exist on the specified date. 

By default (without a -r or -d flag), theversionsto be tagged are supplied implicitly by the evs records of your working files' 
history rather than applied explicitly. 

If you use evs tag -d symbolic tag..., thesymbolic tag you specify isdeldted instead of being added. 


WARNING 


Be very certain of your ground before you delete a tag; doing this effectively discards some historical information, which 
may later turn out to have been valuable 


evs tag will not move a tag that already exists With the -f option, however, evs tag will relocate any instance of symbolic 
tag that already exists on that file to the new repository versions W ithout the -f option, attempting to use evs tag to apply a 
tag that already exists on thatfilewill produce an error message. 

The -b option makes thetag a branch tag, allowing concurrent, isolated da/elopment. This is most useful for creating a patch 
to a pra/iously released software distribution. 

N ormally, tag executes recursively through subdirectories; you can prevent this by using the standard -1 option, or specify 
the recursion explicitly by using -r. 

■ update [-Adf IPpQqR][-d][-r tag j-D date] files... 

Requires: Repository, working directory 

Changes: Working directory 

After you've run checkout to create your private copy of source from the common repository, other developers will continue 
changing the central source From time to time when it is convenient in your development process, you can use the update 
command from within your working directory to reconcile your work with any revisions applied to the source repository 
since your last checkout or update. 

update keeps you informed of its progress by printing a line for each file, prefaced with one of the characters u, a, r, m, c, or? 
to indicate the status of the file: 

u file The file was brought up-to-date with respect to the repository. This is done for any file that exists in 

the repository but not in your source and for files that you haven't changed but are not the most 
recent versions available in the repository. 

a f i i e The file has been added to your private copy of the sources, and will be added to the RCS source 

repository when you run evs commit on thefile. Thisis a reminder to you that the file needs to be 
committed. 

r fi 10 Thefile has been removed from your private copy of the sources, and will be removed from the RCS 

source repository when you run evs commit on thefile. This is a reminder to you that the file needs to 
be committed. 

m f i i e Thefile is modified in your working directory, m can indicate one of two states for a file you're working 

on: either there were no modifications to the same file in the repository, so that your file remains as 
you last saw it; or there were modifications in the repository as well as in your copy, but they were 
merged successfully, without conflict, in your working directory. 
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c fi i e A conflict was detected whiletrying to merge your changes to fi i e with changesfromthesource 

repository, f i i e (thecopyin your working directory) is now the output of the rcsmerge(l) command 
on the two versions; an unmodified copy of your file is also in your working directory, with the name 
.#fiie. version, where version isthe RC S revision that your modified file started from. (Note that 
some systems automatically purge files that begin with .# if they havenot been accessed for a few days 
If you intend to keep a copy of your original file, it is a very good idea to rename it.) 

? file file is in your working directory, but does not correspond to anything in the source repository, and is 

notin the list of files for cvs to ignore; see the description of the-i option. 

U se the -a option to reset any sticky tags dates, or -k options. (If you get a working copy of a file by using one of the ■ r, -d, 
or -k options cvs remembers the corresponding tag, date, or kf lag and continues using it on future updates use the -a 
option to make cvs forget these specifications and retrieve the head version of the file). 

The -jbranch option merges the changes made between the resulting revision and the revision that it is based on. (For 
example, if the tag refers to a branch, cvs will merge all changes made in that branch into your working file.) 

With two -j options cvs will merge in the changes between thetwo respective revisions. This can be used to "remove’a 
certain delta from your working file. For example, if thefilefoo.c isbased on revision 1.6 and I want to remove the changes 
made between 1.3 and 1.5,1 might do this: 
example% cvs update -jl.5 -J1.3 foo.c # note the order... 

In addition, each -j option can contain on optional date specification which, when used with branches can limit the chosen 
revision to one within a specific date An optional date is specified by adding a colon (:) to the tag: 

■]Symbolic Tag:Date Specifier 

Use the -d option to create any directories that exist in the repository if they're missing from the working directory. 

(N ormally, update acts only on directories and files that were already enrolled in your working directory.) This is useful for 
updating directories that were created in the repository si nee the initial checkout; but it has an unfortunate side effect. If you 
deliberately avoided certain directories in the repository when you created your working directory (either through use of a 
module name or by listing explicitly the files and directories you wanted on the command line), then updating with -d will 
create those directories, which may not be what you want. 

Use-i name to ignore files whose names match name (in your working directory) during the update. You can specify-i more 
than onceon thecommand lineto specify several files to ignore By default, update ignores files whose names match any of 
thefollowing: 

RCSLOG RCS SCCS 
CVS* cvslog.* 
tags TAGS 

.make.state .nse_depinfo 

.old *.bak *.BAK *.orig *.rej .del-* 

.a *.o *.so *.Z *.elc *.ln core 

Use-i! to avoid ignoring any files at all. 

The standard cvs command options-f, -k, -i, -p, -p, and -r are also available with update. 

FILES 

For more detailed information on cvs supporting files, see cvs(5). 

Files in home directories: 

.cvsrc The cvs initialization file. Lines in this file can be used to specify default options for each cvs 

command. For example the line diff -c will ensure that cvs diff is always passed the-c option in 
addition to any other options passed on the command line 

.evswrappers Specifies wrappers to be used in addition to those specified in thecvsROOT/cvswrappers filein the 

repository. 
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Files in working directories 


CVS 

CVS/Entries 
CVS/Entries.Backup 
CVS/Entries.Static 
CVS/Root 


CVS/Repository 

CVS/Tag 

CVS/Checkin.prog 

CVS/Update.prog 


A directory of cvs administrative files. D o not delete. 

List and status of files in your working directory. 

A backup Of CVS/Entries. 

Flag: do not add more entries on cvs update. 

Pathname to the repository (cvsroot) location at the time of checkout. Thisfile is used instead 
of the cvsroot environment variable if the envi ronment variable is not set. A warning message 
will be issued when the contents of thisfile and the cvsroot environment variable differ. The 
fi le may be overridden by the presence of the cvs_ignore_remote_root envi ronment vari able. 
Pathname to the corresponding directory in the source repository. 

Containsthe per-directory sticky tag or date information. Thisfile is created/updated when you 
specify -r or -d to the checkout or update commands, and no files are specified. 

N ame of program to run on cvs commit. 

N ame of program to run on cvs update. 


Files in source repositories: 


SCVSROOT/CVSROOT 
CVSROOT/commitinfo,v 
CVSROOT/cvswrappers,v 


CVSROOT/editinfo,v 

CVSROOT/history 

CVSR00T/loginfo,v 

CVSROOT/modules,v 

CVSROOT/rcsinfo,v 

CVSROOT/taginfo,v 

MODULE/Attic 

#cvs.lock 

(fcvs.tfl.pid 

#cvs.rfl.pid 


D i rectory of global administrative files for repository. 

Records programs for filtering cvs commit requests 

Records cvs wrapper commands to be used when checking files into and out of the repository. 

W rappers al low the file or directory to be processed on the way i n and out of cvs. T he i ntended 

uses are many; one possible use would be to reformat a C file before the file is checked in, so all 

of the code i n the repository looks the same 

Records programsfor editingfvalidating cvs commit log entries 

Log file of cvs transactions. 

Records programsfor piping cvs commit log entries 
Definitions for modules in this repository. 

Records pathnames to templates used during a cvs commit operation. 

Records programsfor validating/logging cvs tag and cvs rtag operations 
D i rectory for removed source fi les. 

A lock directory created by cvs when doing sensitive changes to the RCS source repository. 

T emporary lock file for repository. 

A read lock. 

A write lock. 


ENVIRONMENT VARIABLES 


CVSROOT 


CVSREAD 

RCSBIN 

CVSEDITOR 

CVS_IGN0RE_REM0TE_R00T 


Should contain the full pathname to the root of the cvs source repository (where the RCS files 
are kept). This information must be availableto cvs for most commands to execute; if cvsroot 
is not set, or if you wish to override it for one invocation, you can supply it on the command 
line: cvs -d cvsroot cvs command.... You may not need to set cvsroot if your cvs binary has the 
right path compiled in; use cvs -v to display all compiled-in paths. 

If this is set, checkout and update will try hard to makethefilesin your working directory read¬ 
only. W hen this is not set, the default behavior is to permit modification of your working files 
Specifies the full pathname where to find RCS programs such asco(l)and ci(l). If not set, a 
compiled-in value is used; see the display from cvs -v. 

Specifies the program to use for recording log messages during commit. If not set, the editor 
environment variable is used instead. If editor is not set either, the default is/usr/ucb/vi. 

If this variable is set, then cvs will ignore all references to remote repositories in thecvs/Root 
file. 
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cvs_rsh cvs uses the contents of this variable to determine the name of the remote shell command to use 

when starting a cvs server. If thisvariable is not set then rsh is used. 
cvs_server cvs uses the contents of this variable to determine the name of the cvs server command. If this 

variable is not set then cvs is used. 

cvswrappers This variable is used bythecvswrappers scriptto determine the name of the wrapper file, in 

addition to the wrappers defaults contained in the repository (cvsROOT/cvswrappers) and the 
user's home directory r /. cvswrappers). 


AUTHORS 

Dick G rune 

Brian Berliner 
Jeff Polk 


Original author of the cvs shell script version posted to comp, sources, unix in the volume 6 
release of D ecember, 1986. C redited with much of the cvs conflict resolution algorithms. 

Coder and designer of the cvs program itself in April, 1989, based on the original work done by 
Dick. 

H elped Brian with the design of the cvs module and vendor branch support and author of the 
checkin(l) shell script (the ancestor of cvs import). 


SEE ALSO 

ci( 1), co(1), cvs(5), cvsbug(8), diff(l), grep(l), patch(l), rcs(l), rcsdiff(l), rcsmerge(l), rlogbug(8) 
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date 

date— Show and set date and time 

SYNOPSIS 

date [ -u ][-c ] [—n ][-d dsttype ] [ -t mi n u t e s - we s t ] [ -a [ + !-]sss. f f f ] [+f ormat ][ 

[yyyy ]mmddhhmm[yy ] [. ss ]] 

DESCRIPTION 

D ate without arguments writes thedate and time to the standard output in theform: 

Wed Mar 8 14:54:40 EST 1989 

with est replaced by the local timezone'sabbreviation (or by the abbreviation for the time zone specified in theiz environ¬ 
ment variable if set). T he exact output format depends on the locale. 

If a command-line argument starts with a plus sign (+), the rest of the argument is used as a format that controls what 
appears in the output. In the format, when a percent sign (%) appears, itand thecharacter after it arenot output, but rather 
identify part of the date or time to be output in a particular way (or identify a special character to output): 


Argument 

Sample output 

Explanation 

%a 

Wed 

Abbreviated weekday name" 

%A 

Wednesday 

Full weekday name* 

%b 

Mar 

Abbreviated month name" 

%B 

March 

Full month name* 

%c 

Wed Mar 08 14:54:40 1989 

Date and time* 

%C 

19 

Century 

%d 

08 

D ay of month (always two digits) 

%D 

03/08/89 

M onth/day/year (eight characters) 




date 




Argument 

Sample output 

Explanation 

%e 

8 

D ay of month (leading zero blanked) 

%h 

Mar 

Abbreviated month name* 

%H 

14 

24-hour-dock hour (two digits) 

%I 

02 

12-hour-dock hour (two digits) 

M 

067 

J ulian day number (three digits) 

%k 

2 

12-hour-dock hour (leading zero blanked) 

%1 

14 

24-hour-dock hour (leading zero blanked) 

%m 

03 

M onth number (two digits) 

%M 

54 

M inute(two digits) 

%n 

nn 

Newline character 

%p 

PM 

AM/PM designation 

%r 

02:54:40 PM 

Hour:minute:second AM/PM designation 

%R 

14:54 

Hounminute 

%S 

40 

Second (two digits) 

%t 

nt 

T ab character 

%T 

14:54:40 

H ounminute: second 

%U 

10 

Sunday-based week number (two digits) 

%w 

3 

D ay number (one digit, Sunday is 0) 

%W 

10 

M onday-based week number (two digits) 

%x 

03/08/89 

Date* 

%X 

14:54:40 

Time* 

%y 

89 

Last two digits of year 

%Y 

1989 

Year in full 

%Z 

EST 

Time zone abbreviation 

% + 

Wed Mar 8 14:54:40 EST 198 

9 D efault output format* 

* T he exact output depends on the locale. 



If a character other than one of those shown in the preceding table appears after a percent sign in the format, that following 
character is output. All other characters in the format are copied unchanged to the output; a newline character is always 
added at the end of the output. 


In Sunday-based week numbering, the first Sunday of the year begins week 1; days preceding it are part of week 0. In 
M onday-based week numbering, the first M onday of the year begins week 1. 


To set the date use a command-line argument with one of thefollowing forms: 

1454 24-hour-dock hours (first two digits) and minutes 

081454 M onth day (first two digits), hours, and minutes 

03081454 M onth (two digits, January is 01), month day, hours, minutes 

8903081454 Year, month, month day, hours, minutes 

0308145489 M onth, month day, hours, minutes, year (on System V-compatiblesystems) 

030814541989 M onth, month day, hours, minutes, four-digit year 

198903081454 Four-digit year, month, month day, hours, minutes 
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If the century, year, month, or month day is not given, the current value is used. Any of the preceding forms may be 
followed by a period and two digits that give the seconds part of the new time; if no seconds are given, zero is assumed. 

T hese options are avail able: 

-u or -c U se G M T when setting and showing the date and time. 

-n D o not notify other networked systems of the time change. 

-d dsttype Set the kernel-stored Daylight Saving Timetype to thegiven value. (The kernel-stored D ST type is 

used mostly by "old" binaries) 

-t mi nut es- west Set thekernel-stored "minutes west of GMT" value to the one given on the command line (The 

kernel-stored DST type is used mostly by "old" binaries) 

-a adj ust ment Change the time forward (or backward) by the number of seconds (and fractionsthereof) specified 

in the adjustment argument. Either the seconds part or the fractions part of the argument (but not 
both) may be omitted. 0 n BSD -based systems, the adjustment is made by changing the rate at 
which time advances; on System-V-based systems, the adjustment is made by changing the time. 

FILES 

/usr/nb/iocaie/L/LC time DescriptionoftimelocaleL 

/usr/iocai/etc/zoneinfo Timezoneinformation directory 

/usr/local/etc/zoneinfo/localtime Local time ZOnefile 

/usr/local/etc/zoneinfo/posixrules Used With POSIX-StyleTZs 

/usr/local/etc/zoneinfo/GMT ForUTC leap seconds 

If /usr/local/etc/zoneinfo/GMT is absent, UTC leap Seconds are loaded from /usr/local/etc/zoneinfo/posixrules. 

dd 

dd— Convert a file while copying it (data dumper) 

SYNOPSIS 

dd [-help] [-version] [ if =f i I e ] [ of =f i I e ] [ ibs=b y t e s ] [ obs=b y t e s ] [ bs=b y t e s ] 

[cbs=bytes] [skip=bI ocks ] [seek=blocks ] [count=bIocks] [conv={ascii, 
ebcdic, ibm, block, unblock, lease, ucase, swab, noerror, notrunc, sync}] 

DESCRIPTION 

This manual page documents the GN U version of dd. dd copies a file (from the standard input to thestandard output, by 
default) with a user-selectable blocksize, while optionally performing conversions on it. 

OPTIONS 

N umbers can be followed by a multiplier: 


Print a usage message on standard output and exit successfully. 
Print version information on standard output then exit successfully. 
Read from file instead of the standard input. 

Write to file instead of the standard output. Unless conv=notrunc 
file to the size specified by seek= (0 bytes if seek= is not given). 

Read bytes bytesatatime 
Writebyt es bytesatatime. 

Read and writebyt es bytesatatime. Overrideibs and obs. 


T hese options are avail able: 



is given, truncate 
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Convert bytes bytesatatima 

Skip bi ocks ibs-sized blocks at start of input. 

Skip bi ocks obs-sized blocks at start of output. 

Copy only bi ocks ibs-sized input blocks 

Convert the file as specified by the conversion arguments. 

Convert EBCDIC to ASCII. 

Convert ASCII to EBCDIC. 

Convert ASCI I to alternate EBCDIC. 

Pad newline-terminated records to size of cbs, replacing newline with trailing spaces 
Replace trailing spaces in cbs-sized block with newline. 

Change uppercase characters to lowercase 
C hange lowercase characters to uppercase 

Swap every pair of input bytes. Unlike the UN IX dd, this works when an odd 
number of bytes are read. If the input file contains an odd number of bytes, the last 
byte is simply copied (since there is nothing to swap it with). 

Continue after read errors 

D o not truncate the output file 

Pad every input block to size of tbs with trailing nulls. 

GNU FileUduties 


depmod,modprobe 

depmod, modprobe- H andle loadable modules automatically 

SYNOPSIS 



DESCRIPTION 

These utilities are intended to make a Linux modular kernel manageable for all users administrators, and distribution 
maintainers. 

depmod creates a makefilelike dependency file based on the symbols it finds in the set of modules mentioned on the 
command line (or in a default place). This dependency file can later be used by modprobe to automatically load the relevant 
module! s). 

modprobe isused to load a set of modules- either a single module, a stack of dependent modules or all modules that are 
marked with a specified tag. 

modprobe will automatically load all base modules needed in a module stack, as described by the dependency file modules, dep. 
If the loading of one of these modulesfai Is, the whole current stack of modules will be unloaded (by rmmod) automatically, 
modprobe hastwo waysof loading modules 0 ne way (the probe mode) will try to load a module out of a list (defined by 
pattern). It stops loading as soon asone module load successfully. This can be used to autoload one Ethernet driver out of a 
list, for example. The other way is to load all modules from a list. Thiscan be used to load some modules at boot time 
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With the option -r, modprobe will automatically unload a stack of modules, similar to the way rmmod -r does. 

Option -i combined with option -t lists all available modules of a certain type An enhanced mount command could use the 
command: 

modprobe -1 -t fs 

to get the list of all filesystem drivers available and on request load the proper one. So, the mount command could become 
more generic as wel I. (T he kerneid solves this without changi ng the mount utility.) 

Option -c will print all configuration (default +configuration file). 

The normal use of depmod isto include the line /sbin/depmod -a in one of there-files in /etc/rc.d, so that the correct 
module dependencies will be available immediately after booting the system. 

Option -d puts depmod in debug mode. It outputs all commands it is issuing. 

0 ption -e outputs the list of unresolved symbol for each module, N ormally, depmod only outputs the list of unloadable 
modules. 

0 ption -v outputs the list of all processed modules 

M odules may be located at different place in the filesystem, but there will always be some need to override this, especially for 
module developers We expect some official standard will emerge, defined bytheFSSTN D. Until that time, you might as 
well use this suggested directory structure 

CONFIGURATION 

The behavior of depmod and modprobe can be adjusted by the (optional) configuration file/etc/conf. modules. 

The configuration file consists of a set of lines All empty lines, and all text on a line after a#, will be ignored. Lines may be 
continued by ending the line with a \. The remaining lines should all conform to one of the following formats 

keep 

parameter=value 

options module symbol=value ... 
alias module real_name 
pre-install module command ... 
install module command ... 
post-install module command ... 
pre-remove module command ... 
remove module command ... 
post-remove module command ... 

parameter=value options module symbol=value ... alias module real_name 

All values in the parameter lines will be processed by a shell, which means that shell tricks like wildcards and commands 
enclosed in backquotes can be used: 
path[misc]=/lib/modules/1.1.5?/misc 
path[net]=/lib/modules/'uname -r 1 /net 

Parameters may be repeated multiple times 
These are the legal parameters: 

dept iie=DEPFi le_path This is the path to the dependency file that will be created by depmod and used by modprobe. 

path=soME_PATH T he path parameter specifies a directory to search for the modules 

path[tag]= some_path The path parameter can carry an optional tag. Thistells us a little more about the purpose of the 
modules in this directory and allows some automated operations by modprobe. The tag is appended 
to the path keyword enclosed in square brackets Ifthetag is missing, the tag misc isassumed. One 
very useful tag is boot, which can be used to mark all modules that should be loaded at boot time 


If the configuration file /etc/conf. modules is missing, or if any parameter is not overridden, the following defaults are 
assumed: 
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depfile=/lib/modules/ 1 uname -r'/modules.dep 
path[boot]=/lib/modules/boot 

path[fs]=/lib/modules/'uname -r /fs 
path[misc]=/lib/modules/ 1 uname -r'/misc 
path[net]=/lib/modules/'uname -r'/net 
path[scsi]=/lib/modules/'uname -r'/scsi 

path[fs]=/lib/modules/default/fs 
path[misc]=/lib/modules/default/misc 
path]net]=/lib/modules/default/net 
path[scsi]=/lib/modules/default/scsi 


path[fs]=/lib/modules/fs 
path]misc]=/lib/modules/misc 
path[net]=/lib/modules/net 
path[scsi]=/lib/modules/scsi 

All option lines specify the default optionsthat are needed for a module, asin 

modprobe de620 bnc=1 

These options will be overridden by any options given on the modprobe command line. 

The alias lines can be used to give alias names to modules. A linein /etc/cont.modules that looks like this: 
alias iso9660 isofs 

makes it possible to write modprobe iso9660, although thereisno such module available. 

STRATEGY 

T he idea is that modprobe will look first at the directory containing modules compiled for the current release of the kernel. If 
the module is not found there, modprobe will look in the directory containing modules for a default release 
When you install anew Linux, the modules should be moved to a directory related to the release (and version) of the kernel 
you are installing. Then you should do asymlinkfrom this directory to the default directory. 

Each time you compilea new kernel, thecommand make moduies_instaii will create a new directory, but won't change the 
default. 

When you gdt a module unrelated to the kernel distribution, you should place it in one of the version-independent 
directories under /lib/moduies. 

This is the default strategy, which can be overridden in /etc/cont. modules. 


EXAMPLES 

modprobe -t net 
modprobe -a -t boot 
modprobe slip.o 


modprobe -r slip.o 


Load one of the modules that are stored in the directory tagged net. Each module istried until one 
SUCCeedS. (Default: /lib/modules/net). 

All modules that are stored in the directory tagged boot will beloaded. (Default: /iib/moduies/ 
boot). 

This will attempt to load the module sihc.o if it was not previously loaded, since the slip module 
needsthe functionality in thesihc module. This dependency will be described in the file 
modules.dep that was created automatically by depmod. 

Will unload slip.o. It will also unload sihc.o automatically, unless it is used by some other module 
as well (such asppp.o). 


FILES 

/etc/conf.modules 

/lib/modules/*/modules.dep 

/lib/modules/* 
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SEE ALSO 

lsmod(l), kerneld(8), ksyms(l), modules(2) 

REQUIRED UTILITIES 

insmod(l), nm(l) rmmod(l) 

NOTES 

The pattern supplied to modprobe will often be escaped to ensure that it is evaluated in the proper context. 

AUTHOR 

JacquesGelinas(jack@soiucorp.qc.ca), Bjorn Ekwall (bj0m@biox.se) 

BUGS 

Naah... 

Linux, 14 May 1995 

df 

df- Summarize free disk space 

SYNOPSIS 

df [-aikPv] [-tfstype] [-xfstype] [—all] [-inodes] [ — type=f st ype ] 

[ — exclude-type=fstype ] [-kilobytes] [-portability] [-print-type] 

[ — help] [—version] [filename...] 

DESCRIPTION 

This manual page documents the G N U version of df. df displays the amount of disk space availableon thefilesystem 
containing each filename argument. If no filename is given, the space available on all currently mounted filesystems is shown. 
Disk space isshown in IK blocks by default, unless the environment variable posixly_correct isset, in which case 512-byte 
blocks are used. 

If an argument istheabsolute filename of a disk device node containing a mounted filesystem, df shows thespace available 
on that filesystem rather than on thefilesystem containing the device node (which is always the root filesystem). This version 
of df cannot show the space available on unmounted filesystems, because on most kinds of systems doing so requires very 
nonportable, intimate knowledge of filesystem structures. 

OPTIONS 

-a, -aii Include in the listing filesystems that have 0 blocks, which are omitted by default. Such 

filesystems are typically special-purpose pseudo-filesystems, such as automounter entries. On 
some systems, filesystemsof type ignore or auto are also omitted by default and included in the 
listing by this option. 

-i, -inodes List inode usage information instead of block usage An inode (short for "index node;’) is a 

special kind of disk block that contains information about a file such asits owner, permissions, 
timestamps, and location on thedisk. 

-k, -kilobytes Print sizes in IK blocks instead of 512-byte blocks Thisoverridestheenvironment variable 

POSIXLY_CORRECT. 

-p, -portability U se the posix output format. T his is like the default format except that the information about 

each filesystem is always printed on exactly one line; a mount device is never put on a line by 
itself. This means that if the mount device name is more than 20 characters long (as for some 
network mounts), the columns are misal igned. 
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-T, -print-type 
-t, —type=f stype 
-x, —exclude-type=f stype 

— version 

GNU File Utilities 


Print a type string for each filesystem. Any such printed filesystem type name may be used as an 
argument to either of the -type= or -exciude-type= options 

Limitthelisting to filesystems of type f s t y p e . M ultiple filesystem typescan be shown by giving 
multiple -t options. By default, all filesystem types are listed. 

Limitthelisting to filesystems not of type fstype. M ultiplefilesystem typescan be eliminated by 
giving multiple -x options By default, all filesystem types are listed. 

Ignored; for compatibility with System V versions of df. 

Print a usage message on standard output and exit successfully. 

Print verson information on standard output then exit successfully. 


dig 

dig- Send domain name query packets to name servers 

SYNOPSIS 

[fcoment ] 

DESCRIPTION 

dig (domain information groper) isa flexible command-linetool that can be used to gather information from the D omain 
Name System servers, dig has two modes: simple interactive mode that makes a single query, and batch that executes a query 
for each in a list of several query lines. All query options are accessible from the command line. 

The usual simple use of dig takes theform: 

dig Server domai n query-type query-cl ass 

where 

server M ay be either a domain name or a dot-notation Internet address. If this optional field isomitted, 

dig will attempt to use the default name server for your machine. 


NOTE 


If a domain name isspecified, thiswill be resolved using thedomain name system resolver (bind). If your system doesnot 
support DNS, you may have to specify a dot-notation address. Alternatively, if there is a server at your disposal some¬ 
where, all that isrequired isthat /etc/resoiv.cont be present and indicate where thedefault name servers reside so that 
server itself can be resolved. See resoiver(5) for information on /etc/resoiv.conf. 


WARNING 


Changing /etc/resoiv.cont will affect the standard resolver library and potentially several programs that use it.) As an 
option, theuser may set theenvironment variable localres to namea file which isto be used instead of /etc/resoiv.cont 
(localres is specific to the dig resolver and not referenced by the standard resolver). If the localres variable is not set or 
thefile is not readable then /etc/resoiv.cont will be used. 


Thedomain name for which you are requesting information. See "Options" [ -x] for a convenient 
way to specify inverse address query. 
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The type of information (DNS query type) that you are requesting. If omitted, the default is a (t_a 
= address). T hefollowing types are recognized: 


Type Example Description 


a t_a N etwork address 

any t_any All/any information about specified domain 

mx t_mx M ail exchanger for the domain 

ns t_ns Name servers 

soa t_soa Zone of authority record 

hinto t_hinfo H ost information 

axfr t_axfr Zone transfer (must ask an authoritative server) 

txt t_txt Arbitrary number of strings 

(See RFC 1035 for the complete list.) 


The network class requested in the query. If omitted, the default is in (c_in = internet). The 
following classes are recognized: 

in c_in Internet class domain 

any c_any All/any class information 

(See RFC 1035 for the complete list.) 


NOTE 


any can beused to specify a dassand/or a type of query, dig will parse the first occurrence of any to mean query-type = 

To specify query-class = c_any you must either specify any twice, or set query-class using -c option. (See"Other Op¬ 
tions," next.) 


OTHER OPTIONS 

%ignored-comment % is used to include an argument that issimply not parsed. This may be useful if running dig in 
batch mode. I nstead of resolving every @s erver- domai n-name in a list of queries, you can avoid the 
overhead of doing so, and still have the domain name on the command line as a reference. 
Example: 

dig @128.9.0.32 %venera.isi.edu mx isi.edu 

-<dig opt i on > - isused to specify an option thataffectstheoperation of dig. T hefollowing options are currently 

available (although not guaranteed to be useful): 

-x dot-notati on- address Convenient form to specify inverse address mapping. Instead of 

dig 32.0.9.128.in-addr.arpa 

one can simply use 
dig-x 128.9.0.32 

-f file Filefor dig batch mode. The file contains a list of query 

specifications (dig command lines) which are to be executed 
successively. Linesbeginningwith ;,#, or \n areignored. Other 
options may still appear on the command line, and will bein 
effect for each batch query. 

-t ti me Timein seconds between start of successive queries when running 

in batch mode Can be used to keep two or more batch dig 
commands running roughly in sync. Default iszero. 
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-p port 

-P[pi ng- string] 


-t query-type 


-c query-cl ass 


Port number. Q uery a name server listening to a nonstandard port 
number. Default is53. 

After query returns, execute a ping(8) command for response time 
comparison. This rather unelegantly makes a call to the shell. T he 
last three lines of statistics is printed for the command: 
ping-sserver_name56 3 

Iftheoptional ping string ispresent, it replaces ping -sin the 
shell command. 

Specify type of query. M ay specify either an i nteger value to be 
included in thetype field or use the abbreviated mnemonic as 
discussed earlier (mx = t_mx). 

Specify class of query. M ay specify either an integer value to be 
included in the class field or use the abbreviated mnemonic as 


-envsav This flag specifies that the dig environment (defaults, print options, and soon), after all of the 

arguments are parsed, should be saved to afileto become the default environment. Useful if you do 
not like the standard set of defaults and do not desire to include a large number of optionseach 
time dig is used. The environment consists of resolver state variable flags, timeout, and retries as 
well as the flags detailing dig output (see below). If the shell environment variable localdef is set to 
the name of a file, this is where thedefault dig environment issaved. If not, thefile DiG.env is 
created in thecurrent working directory. 


I NOTE 1 

localdef is specific to the dig resolver, and will not affect operation of the standard resolver library. 


Each timedig isexecuted, it looks for ./DiG.env or the file specified by the shell environment 
variable localdef. If such file exists and is readable, then the environment is restored from thisfile 
bdere any arguments are parsed. 

Thisflag only affects batch query runs When -envset is specified on a line in a dig batch file, the 
dig environment after the arguments are parsed, becomes the default environment for the duration 
of the batch file, or until the next line which specifies-envset. 

-[nojstick 

Thisflag only affects batch query runs It specifies that the dig environment (as read initially or set 
by -envset switch) isto be restored before each query (line) in a dig batch file Thedefault -nostick 
means that the dig environment does not stick, hence options specified on a single line in a dig 
batch file will remain in effect for subsequent lines (that is they are not restored to the sticky 
default). 

+<query opt i on> 

+ is used to specify an option to be changed in the query packet or to change dig output specifics. 

M any of these are the same parameters accepted by nsiookup(8). If an option requires a parameter, 
theform isas follows: 


+keyword[=value] 

M ost keywords can be abbreviated. Parsing of the +optionsis very simplistic- a value must not be 
separated from its keyword by whitespace. The following keywords are currently available: 

Keyword Abbre/iation 

M eaning (Default) 

[nojdebug (deb) 

T urn on/off debugging mode [deb] 

[no]d2 

Turn on/off extra debugging mode [nod2] 

[no]recurse (rec) 

U s^don't use recursive lookup [rec] 

retry=# (ret) 

Set number of retries to #[4] 
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Keyword Abbreviation 

M eaning (Default) 

tim 

=#(ti) 

Set timeout length to #seconds[4] 


ko 

Keep open option (implies vc) [noko] 


VC 

Us^don't use virtual circuit [novo] 


defname (def) 

U se^don't use default domain name [def] 


search (sea) 

U se^don't use domain search list [sea] 

dom 

in=NAME (do) 

set default domain name to name 


ignore (i) 

Ignore/don't ignoretrunc. errors [noi] 


primary (pr) 

U s^don’t use primary server [nopr] 


aaonly (aa) 

Authoritative query only flag [noaa] 


sort (sor) 

Sort resource records [nosor] 


cmd 

Echo parsed arguments [cmd] 


stats (st) 

Print query statistics [st] 


Header( h) 

Print basic header [h] 


header(he) 

Print header flags [he] 


ttlid (tt) 

Print TTLs[tt] 


cl 

Print Class info [nocl] 


qr 

Print outgoing query [noqn] 

[no 

reply (rep) 

Print reply [rep] 

[no 

ques (qu) 

Print question section [qu] 

[no 

answer (an) 

Print anaver section [an] 

[no 

author (au) 

Print authoritative section [au] 

[no 

addit (ad) 

Print additional section [ad] 

pfdef 

Sdt to default print flags 

pfm 

n 

Set to minimal default print flags 

pfset=# 

Set print flags to # (# can be hex/octal/decimal) 

pfand=# 

Bitwise and print flags with # 

pfo 

=# 

Bitwise or print flags with # 

The retry and time options affect the retransmission strategy used by resolver library when sending datagram queries. The 
algorithm isasfollows: 

August 30, 1990 

for i = 0 to retry - 1 

for j = 1 to num_servers 


((time * (2**i)) / num_server 


N ote that dig always uses a value of 

DETAILS 

1 for num_servers. 

dig 

once required a slightly modified version of the bind resolver (3) library, bind's resolver has (as of bind 4.9) been 

augmented to work properly with dig. Essentially, dig is a straightforward (albeit not pretty) effort of parsing arguments and 

setting appropriate parameters, dig 
structure. 

uses resolver routines res_init(), resjnkqueryO, res_send() aswell as accessing _res 
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FILES 

/etc/resoiv.conf Initial domain name and nameserver addresses 

ENVIRONMENT 

LOCALRESfiletO USein place of /etc/resolv.conf 
localdef default environment file 

AUTHOR 

Steve H otz (hotz@isi.edu) 

ACKNOWLEDGMENTS 

dig uses functions from nsiookup(8) authored by Andrew Cherenson. 

BUGS 

dig hasaseriouscase of "creeping featurism,"the result of considering several potential uses during its development. It would 
probably benefit from a rigorousdiet. Similarly, the print flags and granularity of the items they specify make evident their 
rather ad hoc genesis. 

dig does not consistently exit nicely (with appropriate status) when a problem occurs somewhere in the resolver (Most of the 
common exit cases are handled.) This isparticularly annoying when running in batch mode. If it exits abnormally (and is not 
caught), the entire batch aborts; when such an event is trapped, dig simply continues with the next query. 

SEE ALSO 

named(8), resolver(3), resolver(5), nslookup(8) 

30 August 1990 


dnsquery 

dnsquery— Q uery domain name servers using resolver 

SYNOPSIS 

dnsquery [-n nameserver] [-t type] [-c class] [-r retry] [-p retry period] 

[-d] [-s] [-v] host 

DESCRIPTION 

The dnsquery program is a general interface to nameservers via bind resolver library calls The program supports queries to the 
nameserver with an opcode of query. This program is intended to be a replacement or supplement to programs like nstest, 
nsquery, and nsiookup. All arguments except for host and ns are treated without case-sensitivity. 

OPTIONS 

-n The nameserver to be used in the query. N ameservers can appear as either Internet addresses of the form 

w.x.y.z or can appear as domain names, (default: as specified in /etc/resoiv.conf) 

-t The type of resource record of interest. T ypes include: 

a Address 

ns N ameserver 

cname Canonical name 

ptr Domain name pointer 

soa Start of authority 
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wks W ell-known service 

hinfo H ost information 

minfo M ailbox information 

mx M ail exchange 

rp Responsible person 

mg M ail group member 

afsdb DCE or AFS server 

any Wildcard 



T he class of resource records of interest. C lasses include the following: 
in Internet 

hs H esiod 

chaos C haos 

any Wildcard 



-r The number of timesto retry if thenameserver is not responding, (default: 4 ) 

-p Period to wait before timing out. (default: resjtimeout) options field, (default: any answer) 

-d Turn on debugging. This sets the res_debug bit of the resolver's options field, (default: no debugging) 

-s U se a stream rather than a packet. This uses a T C P stream connection with the nameserver rather than a 

U D P datagram. ThissetstheREs_usEvc bit of the resolver's options field, (default: udp) 

-v Synonym for the s flag. 

host T he name of the host (or domain) of interest. 

FILES 

/etc/resolv.conf To get the default ns and search lists 

<arpa/nameser.h> List of usable rr types and classes 
<resoiv.h> List of resolver flags 

SEE ALSO 

nslookup(8), nstest(l), nsquery(l), named(8), resolver(5) 

DIAGNOSTICS 

If the resolver fails to answer the query and debugging has not been turned on, dnsquery will simply print a message like this 

Query failed (rc = 1) : Unknown host 

The value of the return code issupplied by h_errno. 
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BUGS 

Q ueries of a class other than in can have interesting results since ordinarily a nameserver only has a list of root nameservers 
for class in resource records 

Query usesacall to inet_addr() to determine if the argument for the -n option isa valid Internet address. Unfortunately, 
inet_addr() seems to cause a segmentation fault with some (bad) addresses (for example, 1.2.3.4.5). 

AUTHOR 

Bryan Beecher 

10 Mardh 1990 


domainname 

domainname— Set or print domain of current host 

SYNOPSIS 

domainname [ name ] 

DESCRIPTION 

domainname prints the domain name of the current host, from thegetdomainname( 3 ) library call. If an argument is present and 
the effective UID iso, domainname changes the name of the host, with thesetdomainname( 2 ) system call. This is usually done at 
boot time in the /etc/rc.local script. 

FILES 

/etc/rc.local 

SEE ALSO 

getdomainname( 3 ), setdomainname( 2 ), uname(l), uname( 2 ) 

AUTHOR 

LarsWirzenius by substituting in hostname.c 

Linux0.98, 26 December 1992 


dsplit 

dspiit— Split a large file into pieces 

SYNOPSIS 

dsplit [ -size nnn ] [i nput.fi Ie [ output.base ]] 

DESCRIPTION 

dspiit splits binary files into smaller chunks so that they may be placed on floppy disks 

OPTIONS 

-size nnn Specifies the size of each output file, in bytes. Thedefault is 1457000, which isenough to will a 

1.44M B floppy disk. 

i nput.fi 1 e Specifies the name of the file to split up. A - indicates standard input. Thedefault is standard 

input. 
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out put_base Specifies the name of the output files to bewritten. dsplit will append 000,001, ...,tothe 

out put .base. The default is dsplit. 


AUTHOR'S NOTES 

Submitted by: David Arnstein (arnstein@netcom.com) 

Posting number: Volume40, Issue 51 
Archive name: dspitt/part0i 
Environment: MS-DOS,UNIX 

H ereisa portable binary file splitting program. It reads a binary file and splits it into pieces. I use this program to put large 
binary fileson floppy disks. For this reason, the default size of theoutput files is 1,457,000 bytes, which just about fills up a 
1.44M B floppy dii. 

U nlike other binary split programs I have seen, dsplit does not maiioc a huge block of memory, dsplit is suitable for use 
under MS-DOS and other primitive operating systems 

(Theprogram camefrom gatekeeper.dec.com:/pub/usenet/comp.sources.misc/volume 40 /dsplit). 

Linux 1.1, 5 July 1994 


du 

du- Summarize disk usage 


SYNOPSIS 

du [-abcklsxDLS] [-all] [-total] [-count-links] [-summarize] [-bytes] 
[-kilobytes] [-one-file-system] [-separate-dirs] [-dereference] 

[-dereference-args] [-help] [--version] [filename...] 


DESCRIPTION 

This manual page documents the G N U version of du. du displays the amount of disk space used by each argument and for 
each subdirectory of directory arguments. The space is measured in IK blocks by default, unless the environment variable 
posixly_correct isset, in which case 512-byte blocks are used. 


OPTIONS 

-a, -all 

-k, —kilobytes 

-s, —summarize 
-x, -one-file-system 


-L, -dereference 

-S, -separate-dirs 
-help 


D isplay counts for all files, not just directories. 

Print sizes in bytes 

Writeagrand total of all of the arguments after all arguments have been processed. Thiscan 
be used to find out the disk usage of a directory, with some files excluded. 

Print sizes in kilobytes This overridesthe environment variable posixly_correct. 

Count the size of all files, even if they have appeared already in another hard link. 

D isplay only a total for each argument. 

Skip directories that are on different filesystems from the onethat the argument being 
processed is on. 

D ereference symbolic links that are command-line arguments D oes not affect other 
symbolic links Thisis helpful for finding out the disk usage of directories like /usr/tmp 
where they are symbolic links 

D ereference symbolic links (show the disk space used by the file or directory that the link 
points to instead of the space used by the link). 

Count the size of each directory separately, not including the sizes of subdirectories 
Print a usage message on standard output and exit successfully. 

Print version information on standard output, then exit successfully. 
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BUGS 

On BSD systems, du reports sizes that are half the correct values for files that are N FS-mounted from H P-UX systems On 
H P-UX systems it reports sizesthat are twice the correct values for files that are N FS-mounted from BSD systems. This is 
due to a flaw in H P-U X; it also affects the H P-U X du program. 

GNU FileUtilities 


editres 

editres— A dynamic resource editor for X T oolkit applications 

SYNTAX 

editres [ -toolkitoption ... ] 

OPTIONS 

editres accepts all of the standard X Toolkit command-line options (seex(l)). The order of the command-line options is not 
important. 

DESCRIPTION 

editres isa tool that allows users and application developers to view the full widget hierarchy of any X Toolkit application 
that speaks the editres protocol. In addition, editres will help the user construct resource specifications, allow the user to 
apply the resource to the application and view the results dynamically. 0 nee the user is happy with a resource specification, 
editres will append the resource string to theuser'sX Resources file. 

USING editres 

editres provides a window consisting of thefollowing four areas: 

M enu Bar A sdt of pop-up menus that allow you full access to editres's features. 

Panner T he panner provides a more intuitive way to scroll the application tree display. 

M essage Area D isplays information to the user about the action that editres expects 

Application Widget Tree Thisareaisused to display the selected application's widget tree. 

To begin an editres session, select the Gdt Widget Tree menu item from the Command menu. This will change the pointer 
cursor to crosshair. You should now select the application you wish look at by clicking on any of its windows If this 
application understands the editres protocol, editres will display theapplication'swidgettreein its tree window. If the 
application does not understand the editres protocol, editres will inform you of this fact in the message area after a few 
seconds delay. 

After you have a widget tree you may select any of the other menu options. The effect of each of these is described in 
"Commands" next. 

COMMANDS 

Get Widget Tree 

Refresh C urrent W idget Tree 


Allows the user to click on any application that speaks the editres protocol and receive its 
widget tree 

editres only knows about the widgets that exist at the present time M any applications 
create and destroy widgets on thefly. Selecting this menu item will cause editres to ask the 
application to resend its widget tree, thus updating its information to the new state of the 
application. 

For example, xman only creates the widgets for its topbox when it starts up. None of the 
widgets for the manual page window are created until the user actually clicks on the M anual 
Page button. If you retrieved xman's widget tree before the manual page is active, you may 
wish to refresh the widget tree after the manual page has been displayed. This will allow you 
to also edit the manual page's resources. 
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D ump W idget Tree to a File 


Show Resource Box 


Sdt Resource 


Quit 


When documenting applications it is often useful to be able to dump the entire application 
widget tree to an ASCII file. Thisfilecan then be included in the manual page. When this 
menu item is selected, a pop-up dialog isactivated. Typethe name of thefile in this dialog, 
and either select 0 kay, or type a carriage-rdturn. editres will dump the widget tree to this 
file. T o cancel the file dialog, select the Cancel button. 

This command will pop up a resource box for the current application. This resource box 
(described in detail later in thissection) will allow the user to see exactly which resources 
can be set for the widgdt that is currently selected in the widget tree display. Only one 
widget may be currently selected; if greater or fewer are selected, editres will refuse to pop 
up the resource box and put an error message in the M essage Area. 

This command will pop up a simple dialog box for setting an arbitrary resourceon all 
selected widgets. You must type in the resource name, as well as the value. You can usethe 
T ab key to switch between the resource name field and the resource valuefield. 

Exits editres. 


TREECOMMANDS 


TheT ree menu contains several commands that enable operationsto be performed on the widget tree. 


Select Widget in Client 


Select All, Unselect All, 
Invert All 
Select Children, 

Select Parents 
Select D escendants, 
Select Ancestors 
Show W idget N ames, 
Show C lass N am es, 
Show Widget Windows 


Flash Active Widgets 


This menu item allows you to select any widget in the application; editres will then 
highlight the corresponding element the widget tree display. After this menu item is 
selected, the pointer cursor will again turn to a crosshair, and you must click any pointer 
button in the widget you wish to have displayed. Since some widgets are fully obscured by 
tha'r children, it is not possible to get to every widget thisway, but this mechanism does 
give very useful feedback between the elements in the widget tree and those in the actual 
application. 

These functions allow the user to select, unselect, or invert all widgets in the widget tree 

These functions select the immediate parent or children of each of the currently selected 
widgets 

These functions select all parents or children of each of the currently selected widgets. This 
isa recursive search. 

When thetree widget is initially displayed, the labels of each widgdt in the tree correspond 
to the widget names These functions will cause the label of all widgets in the tree to be 
changed to show the class name, IDs, or window associated with each widget in the 
application. T he widget ID s, and windows are shown as hex numbers. 

In addition, there are keyboard accelerators for each of theT ree operations. If the input 
focus is over an individual widget in thetree, then that operation will only affect that 
widget. If the input focus is in theT ree background, it will have exactly the same effect as 
the corresponding menu item. 

The translation entries shown may be applied to any widget in the application. If that 
widget is a child of theT ree widgdt, then it will only affect that widget; otherwise it will 
have the same effect as the commands in the T ree menu. 

This command isthe inverse of the Select W idget in C lient command; it will show the user 
each widget that is currently selected in the widget tree by flashing the corresponding widget 
in the application numFiashes (three by default) timesin the flash-color. 


Key Option 

space U nselect 

w Select 

s Select 

i I nvert 


T randation Entry 

Select(nothing) 

Select(widget) 

Select(all) 

Select(invert) 
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Ke/ 

Option 

T randation Entry 

c 

Select 

Children Select(children) 

d 

Select D escendants 

Select(descendants) 

P 

Select Parent 

Sdect(parent) 

a 

Select Ancestors 

Select( ancestors) 

N 

Show W idget N ames 

Relabel(name) 

C 

Show C lass N ames 

Relabel(class) 

1 

Show Widget IDs 

Relabel(id) 

w 

Show Widget Windows 

Relabel(window) 

T 

T oggle W idget/C lass N ame 

Relabel(toggle) 


Clicking button 1 on a widget adds it to the set of selected widgets Clicking button 2 on a widget deselects all other widgets 
and then selects just that widget. Clicking button 3 on a widget toggles its label between the widget's instance name the 
widget's class name. 


USING THE RESOURCE BOX 


The resource box contains five different areas Each of the areas as they appear on the screen from top to bottom, are 
discussed in thefollowing list: 


The Resource Line 
The Widget N ames and Clc 


N ormal and Constraint Resources 


Resource Value 


This area at the top of the resource box shows the current resource name exactly as it 
would appear if you were to save it to a file or apply it. 

This area enables you to select exactly which widgets this resource will apply to. The 
areacontainsfour lines; thefirst contains the name of the selected widget and all its 
ancestors, and the more restrictive dot (.) separator. The second line contains less 
specific class names of each widget, as well as the less restrictive star (*) separator. 
Thethird line containsasfit of special buttonscalled Any Widget that will generalize 
this level to match any widget. The last line contains a set of special buttonscalled 
Any Widget Chain that will turn the single level into something that matches zero or 
more levels 

The initial state of this area is the most restrictive using the resource names and the 
dot separator. By selecting the other buttons in this area, you can ease the restrictions 
to allow more and more widgets to match the specification. The extreme case isto 
select all the Any W idget Chain buttons which will match every widget in the 
application. Asyou select different buttons, the tree display will update to show you 
exactly which widgets will be affected by the current resource specification. 

T he next area all ows you to select the name of the normal or constrai nt resources 
you wish to set. Some widgets may not have constraint resources, so that area will 
not appear. 

This next area allows you to enter the resource value This value should be entered 
exactly asyou would type a line into your resource file Thus, it should contain no 
unescaped newlines. There areafew special character sequences for this file: 

\n- Thiswill be replaced with a newline. 

\###- Where# is any octal digit. Thiswill be replaced with a single 

byte that contains this sequence interpreted as an octal 
number. For example, a value containing a null byte can be 
stored by specifying \eoo. 

\<new-iine>- This will compressto nothing. 

\ \ - Thiswill compressto a single backslash. 
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Command Area This area contains several command buttons, described in the following list: 

The Set Save File button allows the user to modify file that the resources will be 
saved to. This button will bring up a dialog box that will ask you for a filename; 
after thefilename has been entered, either hit carriage-return or click on the 
Okay button. T o pop down the dialog box without changing the save file, click 
the Cancel button. 

The Save button will append the resource line already described to the end of the 
current save file. If no save file has been set, theSdt Save File dialog box will be 
popped up to prompt the user for a filename. 

TheApply button attempts to perform axtsetvaiues call on all widgets that 
match theresourcelinedescribed earlier. The value specified isapplied directly 
to all matching widgdts This behavior is an attempt to give a dynamic feel to the 
resource editor. Since thisfeature allows users to put an application in states it 
may not be willing to handle, a hook has been provided to allow specific 
applicationsto block these setvaiues requests. (See "Blocking editres Requests," 
following). 

Unfortunately, due to design constraints imposed on the widgets by the X 
Toolkit and the Resource M anager, trying to coerce an inherently static system 
into dynamic behavior can cause strange results There is no guarantee that the 
results of an apply will be the same as what will happen when you save the value 
and restart the application. This functionality is provided to try to give you a 
rough feel for what your changes will accomplish, and the results obtained 
should be considered suspect at best. FI avingsaid that, this isone of the neatest 
features of editres, and I strongly suggest that you play with it, and see what it 
can do. 

The Save and Apply button combines the Save and Apply actions described 
earlier into one button. 

ThePopdown ResourceBox button will remove the resource box from the 
display. 

BLOCKING editres REQUESTS 

The editres protocol hasbeen built into the Athena Widget set. This allows all applications that are linked against xaw to be 
able to speak to the resource editor. Although this provides great flexibility, and is a useful tool, it can quite easi ly be abused. 
It istherefore possi blefor any xaw application to specify a value for the editresBiock resource to keep editres from divulging 
information about its internals, or to disable the setvaiues part of the protocol. 

editresBiock (C lass Editresbiock) specifies which type of blocking this application wishes to imposeon the editres protocol. 
The accepted values are as follows: 
an Block all requests. 

setvaiues Block all setvaiues requests Asthisistheonly editres request that actually modifiestheapplication, this 
isin effect stating that the application isread-only. 
none Allow all editres requests 

Remember that these resources are set on any xaw application, not editres. They allow individual applicationsto keep all or 
some of the requests editres makes from ever succeeding. Of course, editres is also an xaw application, so it may also be 
viewed and modified by editres (rather recursive, I know); these commands can be blocked by setting the editresBiock 
resource on editres itself. 

RESOURCES 

For editres, the available application resources are as follows: 

numFiashes (Class NumFiashes) specifies the number of times the widgets in the application will be flashed when the Show 
Active W idgetscommand in invoked. 
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fiashTime (Class FiashTime) specifies the mount of time between the flashes described in the preceding entry, 
fiashcoior (C lasstiashcoior) specifies the color used to flash application widgets. A bright color should be used that will 
immediately draw your attention to the area being flashed, such as red or yellow. 

saveResourcesFiie (Class saveResourcesFiie) isthefilethe resource line will be append to when the Save button activated in 
the resource box. 

WIDGETS 

In order to specify resources, it is useful to know the hierarchy of the widgets that compose editres. In the following 
notation, indentation indicates hierarchical structure. The widget class name isgiven first, followed by the widget instance 
name 

Editres editres 

Paned paned 


MenuButton commands 
SimpleMenu menu 
SmeBSB sendTree 
SmeBSB refreshTree 
SmeBSB dumpTreeToFile 
SmeLine line SmeBSB getResourceList 
SmeLine line 


MenuButton treeCommands 
SimpleMenuumenu 

B showClientWidget 
meBSB selectAll 
meBSB unselectAll 
B invertAll 
ne line 

iBSB selectChildren 
iBSB selectParent 
B selectDescendants 
B selectAncestors 
ne line 

B showWidgetNames 
B showClassNames 
B showWidgetIDs 
B showWidgetWindows 
SmeLine line 

SmeBSB flashActiveWidgets 


Panner panner 
Label userMessage 
Grip grip 
Porthole porthole 
Tree tree 

Toggle <name of widget in application> 


TransientShell resourceBox 
Paned pane 
Label resourceLabel 
Form namesAndClasses 
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Toggle class 


Label namesLabel 
List namesList 
Label constraintLabel 
List constraintList 
Form valueForm 
Label valueLabel 
Text valueText 
Box commandBox 
Command setFile 
Command save 
Command apply 
Command saveAndApply 
Command cancel 


ENVIRONMENT 

display To get the default host and display number 

xenvironment To get the name of a resource file that overrides the global resources stored in the resource jianager 
property. 

FILES 

<xRoot>/iib/xn /app-defaults/Editres specifies required resources. 

SEE ALSO 

x(l), xrdb(l), Athena W idget Set 

RESTRICTIONS 

T his is a prototype T here are lots of nifty features I would love to add, but I hope this will give you some ideas about what a 
resource editor can do. 

AUTHOR 

ChrisD. Peterson (formerly M IT X Consortium) 

X Version 11 Release6 

elvis, ex, vi, view, input 

elvis, ex, vi, view, input- The editor 

SYNOPSIS 

elvis [f I ags ] [+c md ] [f i I es... ] 

DESCRIPTION 

elvis is a text editor that emulates vi/ex. 

On systems which pass the program name as an argument, such asU NIX and M inix, you may also install elvis under the 
names ex, vi, view, and input. These extra names would normally belinksto elvis; see the in shell command. 




efu/'s ex, vi, nirn, input 
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When eivis is invoked asvi, it behaves exactly as though it wasinvoked aseivis. H owever, if you invoke eivis as view, then 
the readonly option issdt as though you had given it the -r flag. If you invoke eivis as ex, then eivis will start up in the 
colon command modeinstead of the visual command mode as though you had given it the -e flag. If you invokeeivis as 
input or edit, then eivis will start up in input mode, as though the -i flag was given. 


OPTIONS 


-w winsize 

+command Of -c command 


FILES 

/tmp/elv* 

tags 

.exrcOrelvis.ro 

ENVIRONMENT 

TERM 

TERMCAP 

TERMINFO 

LINES, COLUMNS 

EXINIT 


To the real vi, thisflag means that a pre/iousedit should be recovered, eivis, though, has a 
separate program, called eivrec(l), for recovering files. When you invokeeivis with -r, eivis will 
tell yOU to run elvrec. 

This sets the readonly option, so you won't accidentally overwrite a file 

This sets the safer option, which disables many potentially harmful commands It has not been 

rigorously proven to be absolutely secure, however. 

This causes eivis to start editing at the given tag. 

eivis will search through f i i e for something that looks like an error message from a compiler. It 

will then begin editing the source file that caused the error, with the cursor sitting on the line where 

the error was detected. If you don't explicitly name a file, then erriist is assumed. 

eivis will start up in colon command mode 

eivis will start up in visual command mode 

eivis will start up in input mode 

Sets the window option’s value to winsize. 

If you use the +cominand parameter, then after the first file is loaded, command is executed as an ex 
command. A typical example would be eivis +237 foo, which would cause eivis to start editing 
too and then move directly to line 237. The -c command variant was added for UNIX SysV 
compatibility. 


During editing, eivis stores text in a temporary file For UN IX, this file will usually be stored in 
the / tmp directory, and the first three characters will be eiv. For other systems, the temporary files 
may be stored someplace else; see the version-specific section of the documentation. 

This is the database used by the :tags command and the -t option. It is usually created by the 
ctags(l) program. 

On UN IX-like systems, a file called .exrc in your home directory isexecuted asaseriesof ex 
commands A file by the same name may be executed in the current directory, too. On non-UN IX 
systems .exrc isusually an invalid filename; there, the initialization file iscalled eivis. rc instead. 


This is the name of your terminal's entry in the termcap or terminfo database. T he list of legal 
values varies from one system to another. 

Optional. If your system uses termcap, and the termcap variable is unset, then eivis will read your 
terminal's definition from /etc/termcap. If termcap is set to the full pathname of a file (starting with 
a /) then eivis will look in the named file instead of /etc/termcap. If termcap is set to a value which 
doesn't start with a /, then its value is assumed to be the full termcap entry for your terminal. 
Optional. If your system uses terminfo, and the terminfo variable is unset, then eivis will read your 
terminal's definition from thedatabasein the /usr/iib/terminfo database If terminfo is set, then its 
valueisused as the database name to useinstead of /usr/iib/terminfo. 

Optional. These variables, if set, will override the screen size values given in thetermcap/terminfo 
for your terminal. On windowing systems such as X, eivis has other ways of determining the 
screen size, so you should probably leave these variables unset. 

Optional. This variable can hold ex commands which will be executed instead of the .exrc filein 
your home directory. 
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shell Optional. The shell variable sets the default value for the shell option, which determines which 

shell program is used to perform wildcard expansion in filenames, and also which is used to execute 
filters or external programs The default value on UN IX systems is/bin /sh. 

Note: Under M S-DOS, this variable is called comspec instead of shell, 
home This variable should be set to the name of your home directory, eivis looks for its initialization file 

there; if home is unset, then the initialization file will not be executed. 
tagpath Optional. This variable is used by the ref program, which isinvoked by the shift- k, control-], 

and : tag commands See ref for more information. 

tmp, temp These optional environment variables are only used in non-UN IX versions of eivis. They allow 

you to supply a directory nameto be used for storing temporary files. 

SEE ALSO 

ctags(l), ref(l), elvprsv(l), elvrec(l) 

Elvis-A Cloneof Vi/Ex, the complete eivis documentation. 

BUGS 

There is no Lisp support. Certain other features are missing, too. 

Auto-indent mode is not quite compatible with the real vi. Among other things, o“d and * "d don't do what you might 
expect. 

Long lines are displayed differently. The real vi wraps long lines onto multiple rows of the screen, but eivis scrolls sideways. 

AUTHOR 

SteveKirkendall (kirkenda@cs.pdx.edu) 

M any other people have worked to port eivis to various operating systems To see who deserves credit, run the: version 
command from within eivis, or look in the system-specific section of the complete documentation. 

elvprsv 

eivprsv — Preserve the modified version of a file after a crash 

SYNOPSIS 

elvprsv ["-why eivis died"] /tmp/f i Ie n a me... 
elvprsv -R /tmp/f i I e n a me... 

DESCRIPTION 

eivprsv preserves your edited text after eivis dies. The text can be recovered later, via the eivprsv program. 

For U N IX-like systems you should never need to run this program from the command line It is run automatically when 
eivis isaboutto die and it should be run (via /etc/rc) when the computer is booted. T FIAT'S ALL! 

For non-UN IX systems such asM S-DOS or VM S, you can either use eivprsv the same way asunder UN IX systems (by 
running it from your autoexec.bat file), or you can run it separately with the -r flag to recover thefiles in onestep. 

If you're editing a file when eivis dies (due to a bug, system crash, power failure and so on), then eivprsv will preserve the 
most recent version of your text. T he preserved text is stored in a special directory; it does not overwrite your text file 
automatically. (If the preservation directory hasn't been sdt up correctly, then eivprsv will simply send you a mail message 
describing how to manually run eivprsv.) 

eivprsv will send mail to any user whose work it preserves, if your operating system normally supports mail. 



FILES 

/tmp/eiv* Thetemporaryfilethateiviswasusingwhen it died. 

/usr/preserve/p* The text that is preserved byelvprsv. 

/usr/preserve/index A text file which lists the names of all preserved files, and the names of the /usr/preserve/p* files 
that contain their preserved text. 


BUGS 

Due to the permissions on the/usr/preserve directory, on UN IX systems eivprsv must be run as superuser. This is 
accomplished by making the eivprsv executable be owned by root and turning on its "set user id" bit. 

If you're editing a nameless buffer when eivts dies, then eivprsv will pretend that the file was named too. 

AUTHOR 

Steve Kirkendall (kirkenda@cs.pdx.edu) 

elvrec 

eivrec— Recover the modified version of a file after a crash 

SYNOPSIS 

elvrec [preservedfiIe [newfiIe ]] 

DESCRIPTION 

If you're editing a file when eivis dies, the system crashes, or power fails, the most recent version of your text will be 
preserved. The preserved text is stored in a special directory; it does not overwrite your text file automatically. 

The eivrec program locates the preserved version of a given file and writes it over the top of your text file-or to a new file, 
if you prefer. T he recovered file will have nearly all of your changes 
To see a list of all recoverable files, run eivrec with no arguments. 


NOTE 


If you haven't set up a directory for file preservation, you'll haveto manually run the eivprsv program instead of eivrec. 


FILES 

/usr/preserve/p* T he text that was preserved when eivis died. 

/usr/preserve/index A text file that lists the names of all preserved files, and the names of the /usr/preserve/p* filesthat 
contain their preserved text. 


BUGS 

eivrec isvery picky about filenames. You must tell it to recover thefile using exactly the same pathname as when you were 
editing it. The simplest way to do this is to go into the same directory that you were editing, and invoke eivrec with the 
same filename as eivis. If that doesn't work, then try running eivrec with no arguments, to see exactly which pathname it is 
usingfor thedesired file. 

D ueto the permissionson the /usr/preserve directory, on U N IX systems eivrec must be run as superuser. T his is 
accomplished by making the eivrec executable be owned by root and setting its "set userid" bit. 

If you're editing a nameless buffer when eivis dies, then eivrec will pretend that the file was named too. 
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AUTHOR 

Steve Kirkendall (kirkenda@cs.pdx.edu) 


emacs 

emacs-GNU project emacs 

SYNOPSIS 

emacs [ command-line switches ] [files ... ] 

DESCRIPTION 

GNU emacs is a version of emacs, written by the author of the original (PD P-10) emacs, Richard Stallman. 

The primary documentation of GN U emacs is in theGNU Emacs M anual, which you can read online using info, a 
subsystem of emacs. Please look therefor complete and up-to-date documentation. This man page is updated only when 
someone volunteers to do so; the emacs maintainers' priority goal is to minimize the amount of time this man page takes 
away from other more useful projects. 

The user functionality of GN U emacs encompasses everything other emacs editors do, and it is easily extensible since its 
editing commands are written in Lisp. 

emacs has an extensive interactive help facility, but the facility assumes that you know how to manipulate emacs windows and 
buffers Ctrl-th (backspace or Ctrl +h) enters the Help facility. H el p Tutorial (Ctrl+h t) requests an interactive tutorial that 
can teach beginners the fundamentals of emacs in a few minutes H elp Apropos (Ctrl+h a) helps you find a command given 
its functionality, Help Character (Ctrl+h c) describes a given character's effect, and Help Function (Ctrl-th f) describes a 
given Lisp function specified by name 

emacs's U ndo can undo several steps of modification to your buffers, so it is easy to recover from editing mistakes. 

GNU emacs's many special packages handle mail reading (RMaii) and sending (Mail), outline editing (outline), compiling 
(compile), running subshells within emacs windows (shell), running a Lisp read-eval-print loop (Lisp-interaction-Mode), and 
automated psychotherapy (Doctor). 

There isan extensive reference manual, but users of other emacses should have little trouble adapting even without a copy. 
Users new to emacs will be able to use basic features fairly rapidly by studying thetutorial and using the self-documentation 
features. 

OPTIONS 

T he followi ng options are of general interest: 

file Editfile. 

n-n umber Go to the line specified by number (do not insert a space between the + sign and the number). 

-q Do not load an init file 

-u user Load user's init file 

-t f i i e Use specified file as the terminal instead of using stdin/stdout. This must be the first argument specified 

in the command line. 

Thefollowing options are Lisp-oriented (these options are processed in the order encountered): 

-f function Executethe Lisp function f uncti on. 

-l file Load the Lisp code in thefilef Me. 

Thefollowing options are useful when running emacs asabatch editor: 

-batch Edit in batch mode. The editor will send messages to stdout. Thisoption must be the fi rst in the 

argument list. You must use -1 and -t options to specify files to execute and functions to call. 

Exit emacs while in batch mode. 


-kill 
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USING emacs WITH x 


emacs has been tailored to work well with theX Window System. If you run emacs from under X windows, it will create its 
own X window to display in. You will probably want to start the editor as a background process so that you can continue 
using your original window, 
emacs can be started with the following X switches: 


-font font, -f n font 


-geometry geometry 


-d di spl ayname, -display di spl ayname 


Specifies the program name which should be used when looking up defaults in the 
user'sX resources. This must be the first option specified in the command line. 
Specifies the name that should be assigned to the emacs window. 

Display the emacs window in reverse video. 

Use the "kitchen sink" bitmap icon when iconifying the emacs window. 

Set the emacs window's font to that specified by font. You will find the various X 
fonts in the/usr/iib/xn /fonts directory. N otethat emacs will only accept fixed 
width fonts Under theXll Release 4 font-naming conventions, any font with the 
value m or c in the eleventh field of the font name is a fixed width font. Furthermore 
fonts whose name are of the form widthxheight are generally fixed width, asisthe 
font fixed. See xisfonts(l) for more information. 

W hen you specify a font, be sure to put a space between the avitch and the font 
name 

Set the emacs window's border width to the number of pixels specified by pixels 
Defaults to one pixel on each side of the window. 

Set the window's internal border width to the number of pixels specified by pi xeis. 
Defaults to one pixel of padding on each side of the window. 

Set the emacs window's width, height, and position as specified. Thegeomet ry 
specification isin the standard uformat; seex(l) for more information. The width 
and height are specified in characters; the default is 80 by 24. 

0 n color displays, sdts the color of the text. See the fi le /usr/iib/xi i / rgb . txt for a 
list of valid color names 

On color displays, sets the color of the window's background. 

On color displays, sets the color of the window's border. 

0 n color displays, sdts the color of the window's text cursor. 

0 n color displays, sdts the color of the window's mouse cursor. 

C reate the emacs window on the display specified by d i s p i a y n a me . M ust be the first 
option specified in the command line. 

Tells emacs not to use its special interface to x. If you usethisswitch when invoking 
emacs from an xterm(l) window, display is done in that window. This must be the 
first option specified in the command line 


You can set x default values for your emacs windows in your xresources file see xrdb(l). Use the following format: 


where v a i u e specifies the default value of key wor d . emacs lets you set default values for the following keywords 


font (class Font) 

reverseVideo (class Reversevideo) 
bitmaplcon (daSS Bitmaplcon) 
borderWidth (class BorderWidth) 
internalBorder (daSS BorderWidth) 
foreground (daSS Foreground) 
background (daSS Background) 
borderColor (class BorderColor) 


Sdts the window's text font. 

If reversevideo's value is set to on, the window will be displayed in reversevideo. 
If bitmapl con's value is set to on, the window will iconify into the "kitchen sink." 
Sdts the window’s border width in pixels. 

Sdts the window's internal border width in pixels 
For color displays, sets the window's text color. 

For color displays, sets the window's background color. 

For color displays, sets the color of the window's border. 
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cursorColor (class Foreground) 
pointerColor (class Foreground) 
geometry (daSS Geometry) 

title (Class Title) 
iconName (class Title) 


For color displays, sets the color of thewindow'stext cursor. 
For color displays, sets the color of the window's mouse cursor. 
Sdts the geometry oftheemacs window. 

Sdts the title oftheemacs window. 

Sdts the icon name for the emacs window icon. 


If you try to set color values while using a black-and-white display, the window's characteristics will default as follows The 
foreground color will be set to black, the background color will be set to white, the border color will be set to gray, and the 
text and mouse cursors will be set to black. 


USING THE MOUSE 

Thefollowing lists the mouse button bindingsfor the emacs window under Xll. 


Mouse Button 

Function 

left 

Set point. 

middle 

Paste text. 

right 

Cut text into X cut buffer. 

Shift-middle 

C ut text intoX cut buffer. 

Shift-Fright 

Paste text. 

Ctrl-middle 

C ut text i nto X cut buffer and ki 11 it. 

Ctrl-might 

Select thiswindow, then split it into two windows Same as typing Ctrl+x 2. 

Ctrl+Shift-Heft 

X buffer menu; hold the buttons and keys down, wait for menu to appear, select buffer, and 
release. M ove mouse out of menu and release to cancel. 

C trl+Shift+middle 

X help menu; pop up index card menu for emacs help. 

Ctrl+Shift+right 

Select window with mouse and delete all other windows Same as typing Ctrl 4-x 1. 


MANUALS 

You can order printed copies of the GN U Emacs Manual from the Free Software Foundation, which develops GNU 
software. See thefile orders for ordering information. 

Your local emacs maintainer might also have copies available As with all software and publicationsfrom FSF, everyone is 
permitted to make and distribute copies of the emacs manual. TheTeX source to the manual is also included in theemacs 
source distribution. 

FILES 

/usr/local/info 


/usr/local/lib/emacs/$VERSION/src 

/usr/local/lib/emacs/$VERSION/lisp 

/usr/local/lib/emacs/$VERSION/etc 

/usr/local/lib/emacs/$VERSION/etc/DOC.* 


Files for the info documentation browser (a subsystem of emacs) to 
refer to. Currently not much of U NIX is documented here, but the 
complete text oftheemacs reference manual isincluded in a 
convenient tree structured form. 

C source files and object files 

Lisp source files and compiled files that define most editing com¬ 
mands. Some are preloaded; others are autoloaded from this directory 
when used. 

Various programs that are used with GNU emacs, and some files of 
information. 

Containsthe documentation stringsfor the Lisp primitives and 
preloaded Lisp functions of GNU emacs. They are stored hereto 
reduce the size of emacs proper. 
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/usr/local/lib/emacs/$VERSION/etc/DIFF 
/usr/local/lib/emacs/$VERSION/etc/CCADIFF 
/usr/local/lib/emacs/$VERSION/etc/GOSDIFF 
/usr/local/lib/emacs/$VERSION/etc/SERVICE 


/usr/local/lib/emacs/lock 

/usr/local/lib/emacs/$VERSION/$ARCHITECTURE/cpp 

/usr/lib/XII/rgb.txt 


DiSCUSSesGNU emacs versus Twenex emacs. 

DiSCUSSesGNU emacs VerSUSCCA emacs. 

DiSCUSSesGNU emacs VerSUSGOSling emacs. 

Lists people offering various services to assist users of G N U emacs, 
including education, troubleshooting, porting, and customization. 
These files also have information useful to anyone wanting to write 
programs in the emacs Lisp extension language which has not yet 
been fully documented. 

H olds lock files that are made for all files being modified in emacs, to 
prevent simultaneous modification of one file by two users. 

TheGN U cpp, needed for building emacs on certain versionsof 
UNIX where the standard cpp cannot handle long names for macros. 
List of valid x color names. 


BUGS 

There is a mailing list, bug-gnu-emacs@prep.ai.mit.edu on the Internet (ucbvax lprep.ai.mit.edu! bug -gnu -emacs on 
UUCPnet), for reporting emacs bugs and fixes But before reporting something as a bug, please try to be sure that it really is a 
bug, not a misunderstanding or a deliberate feature. We ask you to read the section "Reporting emacs Bugs" near the end of 
the reference manual (or into system) for hints on how and when to report bugs Also, include the version number of the 
emacs you are running in every bug report that you send in. 

Do not expect a personal answer to a bug report. The purpose of reporting bugs is to get them fixed for everyone in the next 
release, if possible. For personal assistance look in the service file for a list of people who offer it. 

Please do not send anything but bug reports to this mailing list. Send requests to be added to mailing lists to the special list 
info-gnu-emacs-request@prep.ai.mit.edu (or the corresponding UUCP address). For more information about emacs mailing 
lists, seethefile /usr/iocai/emacs/etc/MAiuNGLisTS. Bugstend actually to be fixed if they can be isolated, so itisin your 
interest to report them in such away that they can be easily reproduced. 

One bug that I know about: Shell will not work with programs running in Raw mode on some UN IX versions. 

UN RESTRICTIONS 

emacs isfree; anyone may redistribute copies of emacs to anyone under the terms stated in the emacs General Public License a 
copy of which accompanies each copy of emacs and which also appears in the reference manual. 

Copies of emacs may sometimes be received packaged with distributions of U N IX systems, but it is never included in the 
scope of any license covering those systems. Such inclusion violates the terms on which distribution is permitted. In fact, the 
primary purpose of the General Public License isto prohibit anyone from attaching any other restrictions to redistribution 

Of emacs. 

Richard Stallman encourages you to improve and extend emacs, and urges that you contribute your extensions to the GN U 
library. Eventually GNU (GNU'S Not UN IX) will be a complete replacement for Berkeley UN IX. Everyone will be free to 
use, copy, study, and changetheGN U system. 

SEE ALSO 

X(l), xlsfonts(l), xterm(l), xrdb(l) 

AUTHORS 

emacs was written by Richard Stallman and the Free Software Foundation. Joachim M artillo and Robert Krawitz added theX 

features 

19 April 1994 
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emacstool 

emacstool— Run emacs under Sun windows with function key and mouse support. 

SYNOPSIS 

emacstool [{window_args} {-re run_command_path> args ... ] 

TYPICAL USAGE 

In '/.suntoois or '/.rootmenu, include a line like this 
"Emacstool" emacstool -WI emacs.icon -f emacstool-init 

DESCRIPTION 

emacstool creates a SunView frame and a tty subwindow within which mouse events and function keys are translated to 
ASCII sequences that emacs can parse. The translated input events are sent to the process running in the tty subwindow, 
which istypically GNU emacs. emacstool thereby allows G N U emacs users to make full use of the mouse and function keys 
GNU emacs can be loaded with functionsto interpret the mouse and function-key events to make a truly fine screen-oriented 
editor for the Sun W orkstation. 


NOTE 


GNU emacs hasa special interface to the X Window System as well. TheX Window System has many technical advan¬ 
tages, itisan industry standard, and itisalsofreesoftware.TheFreeSoftwareFoundation urges you to tryX Windows 
and distributes a free copy of x on emacs distribution tapes. 


Function keys are translated to a sequence of the form / V[a-o] [irt]. The last character is 1 , r, ort, corresponding to 
whether the key isamong the Left, Right, or Top function keys Thethird character indicates which button of the group was 
pressed. Thus, the function key in the lower-right corner will transmit the sequence *x*or. In addition, the [irt] is affected 
by the Control, M eta, and Shift keys Unshifted Ctrl keys will benonalphabetic: C-l is [,], C-r is[ 2 ], C-t is [4]. 
Mousebuttonsareencodedas*x'@([i24] x y)\n. *x*@isthe standard GNU emacs mouseevent prefix; it isfollowed by a list 
indicating the button pressed and the character row and column of the point in the window where the mouse cursor is and 
followed by a newline character. In GN U emacs, the 'x"@ dispatches to a mouseevent handler which then reads the following 
list. 

OPTIONS 

emacstool supports all the standard window arguments including font and icon specifiers. 

By default, emacstool runs the program emacs in the created subwindow. The value of the environment variable emacstool 
can be used to override this if your version of emacs is not accessible on your search path by the name emacs. In addition, the 
run command can be set by the pathname following the last occurrence of the -rc flag. T his is convenient for using emacstool 
to run on remote machines 

All other command-line arguments not used by the window system are passed asargumentsto the program that runs in the 
emacstool window. 

For example, 

local% (emacstool -rc rlogin remote -8 &)& 

will create an emacstool window logged in to a machine named remote. If emacs is run from this window, emacstool will 
encode mouse and function keys and send them to rlogin. If emacs is run from this shell on the remote machine it will see 
the mouse and function keys properly. FI owever, since the remote host does not have access to the screen, the cursor cannot 
be changed, menus will not appear, and the selection buffer (stuff) islimited. 
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USING WITH GNU emacs 

TheG N U emacs files lisp/term/sun,el, lisp/sun-mouse.el, lisp/sun-fns. el, and src/sunfns.c provide emacs Support 
fortheemacstooi and function keys, emacstooi will automatically set the term environment variable to be sun and unset 
the environment variable termcap. T hat is, these variables will not be inherited from the shel I that starts emacstooi. Since the 
terminal type is sun (that is, the environment variable term issdtto sun), emacs will automatically load the file usp/term/sun. 
This, in turn, will ensure that sun-mouse, ei is autoloaded when any mouse events are detected. It is suggested that sun-mouse 
and sun-tns be loaded in your site-imt.ei file, so that they will always be loaded when running on a Sun workstation. 

In addition, emacstooi sets the environment variable in_emacstool = "t". Lisp code in your '/.emacs can use (getenv 
" in_emacstool ") to determine whether to do emacstooi-specific initialization, sun.ei usesthisto automatically call emacstooi- 
init if (getenv "in_emacstool" ) is defined. 

The file src/sunfns.c defines several useful functions for emacs on the Sun. Among these are procedures to pop up SunView 
menus, put and get from the SunView stuff buffer, and a procedure for changing the cursor icon. If you want to define or 
edit cursor icons, there is a rudimentary mouse-driven icon editor in thefileiisp/sun-cursors.ei. T ry invoking (sc: edit- 
cursor). 

BUGS 

Ittakesafew milliseconds to createamenu before it pops up. 

ENVIRONMENT VARIABLES 

EMACSTOOL, IN_EMACST00L, TERM, TERMCAP 

FILES 

SEE ALSO 

emacs(l), .../etc/SUN-SUPPORT, .../lisp/term/sun.el 

etags 

etags- Generate tag filefor emacs 
etags— G enerate tag fi le for vi 

SYNOPSIS 

etags [ -aCDSVH] [ -i f i I e ][-o tagfile ] 

[ --C++ ] [ --no-defines] [ --ignore-indentation ] [ --help ] [ --version ] 

[ - -include=f i I e ] [ --output=tagf i I e ] [ --append ] file ... 

etags [ -aCdSVH] [ -BtTuvwx ] [ -o tagfile ] 

[ --C++ ] [ --defines ] [ --ignore-indentation ] 

[ --backward-search] [ --forward-search ] [ --typedefs ] [ --typedefs-and-c++] 

[ --no-warn ] [ --cxref ] [ --help ] [ --version ] 

[ --outputsagfiIe ] [ --append ] [ --update ] file ... 

DESCRIPTION 

The etags program is used to create a tag table file, in a format understood by emacs(l); the etags program is used to create a 
similar table in a format understood by vi(l). Both forms of the program understand the syntax of C, FORTRAN, Pascal, 
LaTeX, Scheme, emacs Lisp/Common Lisp, and most assembler-like syntaxes. Both forms read the files specified on the 
command line, and write a tag table (defaults tags for etags, tags for etags) in the current working directory. The programs 
recognize the language used in an input file based on its filename and contents; there are no switches for specifying the 
language. 
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OPTIONS 


Some options make sense only for the vi-style tag files produced by ctags; etags does not recognize them. The programs 
accept unambiguousabbreviationsfor long option names. 


-a, --append 

-B, - -backward-search 


-i file, - -include=f i I e 


-o tagfile, --outputsagfi I e 


Append to existing tag file. (For vi-format tag files, see also - -update.) 

T ag files written in the format expected by vi contain regular expression search instructions; 
the-B option writes them using the delimiter ?, to search backwards through files. The 
default is to use the deli mi ter / to search forwards through files. Only ctags accepts this 
option. 

Treat files with .c and .h extensions as C++code, note code. Files with .c, .h, .cxx, .hxx, 
or .cc extensions are always assumed to beC++code 

Create tag entries for C preprocessor definitions, too. This is the default behavior for etags, 
so this option is only accepted by ctags. 

Do not create tag entriesforC preprocessor definitions. This may make the tags file much 
smaller if many header files are tagged. This is the default behavior for ctags, so this option 
is only accepted by etags. 

Include a note in tag file indicating that, when searching for a tag, one should also consult 
the tags filet i i e after checking the current file. Only etags accepts this option. 

Explicit name of file for tag table; overrides default tags or tags. (But ignored with -vor 
-x.) 


-S, --ignore-indentation 

-t, - -typedefs 

-T, --typedefs-and-c++ 

-u, --update 

-v, - -vgrind 




Don't rely on indentation as much as we normally do. Currently, this means not to assume 
that a closing brace in the first column isthefinal brace of a function or structure definition 
in C and C++. 

Record typedefs in C code as tags. Since this isthe default behavior of etags, only ctags 
accepts this option. 

Generate tag entries for typedefs, struct, enum, and union tags, and C++member functions. 
Since this is the default behavior of etags, only ctags accepts this option. 

Update tag entries for files specified on command line leaving tag entries for other filesin 
place. Currently, this is implemented by deleting the existing entriesfor the given files and 
then rewriting the new entries at the end of the tags file. It is often faster to simply rebuild 
the entire tag file than to use this Only ctags accepts this option. 

Instead of generating a tag file, write index (in vgrind format) to standard output. 0 nly 
ctags accepts this option. 

Suppress warning messages about duplicate entries The etags program does not check for 
duplicate entries so thisoption is not allowed with it. 

Instead of generating a tag file, write a cross-reference (in cxref format) to standard output. 
0 nly ctags accepts this option. 

Print usage information. 

Print the current version of the program (same as the version oftheemacs etags isshipped 
with). 


SEE ALSO 

emacs entry in info; GNU EmacsM anual, Richard Stallman. 
cxref(l), emacs(l), vgrind(l), vi(l). 

COPYING 

Copyright © 1992 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided the copyright notice and this permission notice are preserved on all copies 
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 



find 


0 


Permission isgranted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in theoriginal English. 

GNU Tools, 19April 1994 

expand 

expand- Convert tabs to spaces 

SYNOPSIS 

expand [-tabl[,tab2[,...]]] [-t tabl[,tab2[,...]]] [-1] [-tabs=tab1[,tab2[,...]]] 

[■■initial] [--help] [--version] [file...] 


DESCRIPTION 

This manual page documents the GN U version of expand, expand writes the contents of each given file or the standard input 
if none are given or when a file named - is given, to the standard output, with tab characters converted to the appropriate 
number of spaces. By default, expand converts all tabs to spaces It preserves backspace characters in theoutput; they 
decrement the column count for tab calculations The default action isequi valent to -8 (set tabs every 8 columns). 

OPTIONS 


--version 

GNU Text Utilities 

find 

find— Search for files in a directory hierarchy 

SYNOPSIS 

find [path...] [expression] 

DESCRIPTION 

This manual page documents the GN U version of find, find searches the directory tree rooted at each given filename by 
evaluating the given expression from left to right, according to the rules of precedence (see "0 perators," later in this manual 
page), until the outcome is known (the left side is False for and operations, True for or), at which point find moves on to the 
next filename. 

Thefirst argument that beginswith-, (,),,, or r istaken to bethe beginning of the expression; any arguments before it are 
paths to search, and any arguments after it are the rest of the expression. If no paths are given, the current directory is used. If 
no expression is given, the expression -print is used. 

find exits with status a if all files are processed successfully, greater than 0 if errors occur. 


,...]] If only one tab stop isgiven, set the tabs t ab 1 spaces apart instead of the default 8. 

Otherwise, set the tabs at columns tab 1, tab 2, and so forth (numbered from 0) and 
replace any tabs beyond the tab stops given with single spaces If the tab-stops are 
specified with the-tor - -tabs option, they can be separated by blanks aswell asby 
commas. 

0 nly convert initial tabs (those that precede all nonspace or tab characters) on each 
line to spaces 

Print a usage message and exit with a nonzero status. 

Print version information on standard output then exit. 
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EXPRESSIONS 

The expression is made up of options (which affect overall operation rather than the processing of a specific file, and always 
return True), tests (which return a True or False value), and actions (which have side effects and return a True or False value), 
all separated by operators -and isassumed where the operator isomitted. If the expression contains no actions other than - 
prune, -print is performed on all files for which the expression is true 


OPTIONS 


All options always return True. They always take effect, rather than being processed only when their place in the expression is 
reached. Therefore for clarity, it is best to place them at the beginning of the expression. 


-daystart 

-help, —help 
-maxdepth levels 

-mindepth Ievels 




M easure times (for -amin, -atime, -cmin, -ctime, -mmin, and -mtime) from the beginning of today 
rather than from 24 hours ago. 

Process each directory's contents before the directory itself. 

D ereference symbolic links Implies -noleaf. 

Printasummary of the command-line usage of find and exit. 

Descend at mosti evei s (a nonnegative integer) levels of directories below the command-line 
arguments, -maxdepth 0 means only apply the tests and actions to the command-line arguments. 

Do not apply any tests or actions at levels less than 1 evei s (a nonnegative integer), -mindepth 1 
means process all files except the command-line arguments. 

Don't descend directories on other filesystems. An alternate name for -xdev, for compatibility with 
some other versions of find. 

Do not optimize by assuming that directories contain two fewer subdirectories than their hard link 
count. This option is needed when searching filesystems that do not follow the UNIX directory- 
link convention, such as CD-ROM or MS-DOS filesystems or AFS volume mount points Each 
directory on a normal UNIX filesystem has at least 2 hard links its name and its. entry. Addition¬ 
ally, its subdirectories (if any) each havea .. entry linked to that directory. When find is examining 
a directory, after it hasstatted two fewer subdirectories than the directory's link count, it knows 
that the rest of the entries in the directory are nondirectories (leaf files in the directory tree). If 
only the files' names need to be examined, there is no need to stat them; this gives a significant 
increase in search speed. 


-version, -version Print thefind version number and exit. 

-xdev D on't descend directories on other filesystems. 


TESTS 


N umeric arguments can be specified as 




-empty 

-false 


G reater than n. 

Less than n. 

Exactly n. 

Filewas last accessed n minutes ago. 

File was last accessed more recently than f i 1 e was modified, -anewer is affected by -miowonlyif- 
foiiow comes before -anewer on the command line. 

Filewas last accessed n *24 hours ago. 

File’sstatuswas last changed n minutesago. 

File's status was last changed more recently than file was modified, -cnewer i s affected by -follow 
only if -follow comes before -cnewer on the command line 
File's status was last changed n *24 hours ago. 

File is empty and is either a regular file or a directory. 

Alwaysfalse. 
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-group gname 
-ilname pattern 


-ipath pattern 
-iregex pattern 

-lnarae pattern 


-name patter 




-regex pattern 


File is on a filesystem of type type. The valid filesystem types vary among different versions of 
UN IX; an incomplete list of filesystem types that are accepted on some version of UNIX or another 
is: ufs, 4 . 2 , 4 . 3 , nfs, tmp, infs, ssiK, S52K. You can use-printf with the%F directive to see the types 
of your filesystems 
File's numeric group ID isn. 

Filebelongsto group gname (numeric group ID allowed). 

Like -iname, but the match is case-in sensitive. 

Like -name, but the match is case-insensitive For example, the patterns to* and f?? match the 
filenames foo, foo, too, too, and so on. 

File has inode number n. 

Like -path, but the match is case-insensitive 
Like -regex, but the match iscase-insensitive. 

Filehasn links 

File is a symbolic link whose contents match shell pattern patter n. The metacharacters do not treat 
/ or. specially. 

File's data was last modified n minutes ago. 

File's data was last modified n*24 hours ago. 

Base of filename (the path with the leading directories removed) matches shell pattern pattern. The 
meta characters (*, ?, and n) do not match a . at the start of the base name. To ignore a directory 
and the files under it, use -prune; see an example in the description of -path. 

File was modified more recently than file, -newer is affected by -follow only if -follow comes before 
-newer on the command line. 

N o user corresponds to file's numeric user ID. 

N o group corresponds to file's numeric group ID. 

Filename matchesshell pattern pattern. The meta characters do not treat / or. specially; so, for 
example, 

find. - path './sr*sc' 

will print an entry for a directory called . /src/misc (if oneexists). T o ignore a whole directory tree 
use -prune rather than checking every file in thetree. For example to skip thedirectory src/emacs 
and all files and directories under it, and print the names of the other filesfound, do something like 
this 

find . -path './src/emacs' -prune-o -print 

File's permission bits are exactly mode (octal or symbolic). Symbolic modes use mode 0 as a point 
of departure. 

All of the permission bits mode are set for the file. 

Any of the permission bits mode are set for the file 

Filename matches regular expression pattern. Thisisa match on the whole path, not a search. For 
example,to match a file named ./fubar3,you can use the regular expression ,*bar. or .*b.*3,but 
not b. *r3. 

File uses n units of space T he units are 512-byte blocks by default or if b follows n, bytes if c 
follows n, kilobytes if k follows n, or 2-byte words if w follows n. T he size does not count indirect 
blocks, but it does count blocks in sparse files that are not actually allocated. 

Always true 

Fileisof typec. Possible types: 
b Block (buffered) special 
c C haracter (unbuffered) special 
d Directory 
p Named pipe (FIFO) 
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-xtype c 


f Regular file I symbolic link 
s Socket 

File'snumeric user ID isn. 

Filewas last accessed n days after its status was last changed. 

Fileisowned by user uname (numeric user ID allowed). 

The same as -type unless thefile is a symbolic link. For symbolic links: if -follow has not been 
given, True if the file is a link to a file of type c; if -follow has been given, True if c Is 1. In other 
words, for symbolic links, -xtype checks the type of thefile that -type does not check. 


ACTIONS 


-fis file 




-fprint0 file 


Execute command; True if 0 status is returned. All following arguments to find are taken to be 
arguments to the command until an argument consisting of; is encountered. The string {} is 
replaced by the current filename being processed everywhere it occurs in the arguments to the 
command, not just in arguments where it is alone, as in some versions of find. Both of these 
constructions might need to be escaped (with a \) nor quoted to protect them from expansion by 
the shell. The command isexecuted in the starting directory. 

True; like -is but write to fi i e like -f print. 

True; print the full filename into file fi i e. If fi i e does not exist when find is run, itiscreated; if it 
does exist, itistruncated.Thefilenames/dev/stdout and /dev/stderr are handled specially; they 
refer to the standard output and standard error output, respectively. 

True; like -print0 but write to file like -fprint. 

True; like-printf but write to file like -fprint. 

Like -exec but ask the user first (on the standard input); if the response does not start with y or y, 
do not run the command, and return False. 

True; print the full filename on the standard output, followed by a newline 

True; print the full filename on thestandard output, followed by a null character. This allows 

filenames that contain newlines to be correctly interpreted by programs that process the find 

output. 

True; print format on thestandard output, interpreting n escapes and % directives Field widths and 
precisionscan be specified aswith theprintf C function. Unlike-print, -printf does not add a 
newline at the end of the string. The escapes and directives are as follows: 

\a Alarm bell 
\b Backspace 

\c Stop printing from thisformat immediately and flush the output 

\f Formfeed 

\n Newline 

\r Carriage return 

\t FI orizontal tab 

\v Vertical tab 

u A literal backslash (V) 

A \ character followed by any other character is treated as an ordinary character, so they both are 
printed: 

%% A literal percent sign. 

%a Filelslast access time in theformat returned by theC ctime function. 

%Ak File's last access time in the format specified by k, which iseither @ or a directivefor the C 
strftime function. T he possible values for k are listed below; some of them might not be 
available on all systems, due to differences in strftime between systems. 
@secondssinceJan. 1,1970, 00:00GMT. 




T ime fields 


h Hour (00.. 23) 

1 H our (01. .12) 

k H our (0. .23) 

1 H our ( 1 . . 12 ) 

m M inute (00. .59) 

p Locale'sa.m. orp.m. 

r Time 12-hour (hh:mm:ss [AP]M) 

u Second (00.. 6 i) 

T Time 24-hour (hh:mm:ss) 

x Locale'stimerepresentation (h:m:s) 

z Time zone (for example EDT), or nothing if notimezoneis 

determinable 

Date fields 

a Locale's abbreviated weekday name(sun, .sat) 

a Locale's full weekday name variable length (Sunday.. Saturday) 

b Locale's abbreviated month name (jan. .Dec) 

b Locale'sfull month name variable length (January.. December) 

c Locale'sdateandtimefsat nov 04 12:02:33 est 1989) 

d Day of month (01. .31) 

D D ate (mm/dd/yy) 

h Same as b 

j Day of year ( 001 .. 366) 

m M onth ( 01 . . 12 ) 

u Week number of year with Sunday asfirst day of week ( 00 . .53) 

w Day of week ( 0 . .6) 

w Week number of year with Monday as first day of week (00.. 53) 

x Locale's date representation (mm/dd/yy) 

y Last two digits of year (00.. 99) 

y Year (1970...) 

%b File'ssizein 512-byte blocks (rounded up). 

%c File'slaststatuschangetimeintheformatrdturned bytheC ctime function. 

%ck File's last status change time in the format specified by k, which isthesameasfor%A. 
%d File's depth in the directory tree; 0 means the file is a command-line argument. 

%f File's name with any leading directories removed (only the last element). 

%f Type of the filesystem thefile is on; this value can be used for-fstype. 

%g File'sgroup name or numeric group ID if the group has no name. 

%g File's numeric group ID. 

%h Leading directories of file's name (all but the last element). 

%h C ommand-line argument under which file was found. 

%i File's inode number (in decimal). 

%k File'ssizein IK blocks (rounded up). 

%i 0 bject of symbolic link (empty string if file is not a symbolic link). 
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%m File's permission bits (in octal). 

%n Number of hard linksto file. 

%p File's name 

%p File's name with thenameof the command-line argument under which itwasfound 
removed. 

%s File's size in bytes 

%t File's last modification time in theformat returned bytheC ctime function. 

%Tk File's last modification time in theformat specified byk, which is the same as for %a. 

%u File's username, or numeric user ID if the user has no name 
%u Fil^snumeric user ID. 

A % character followed by any other character is discarded (but the other character is 
printed). 

-prune If -depth isnot given, True; do not descend the current directory. 

If -depth isgiven, False; no effect. 

-is True; list current file in is -diis format on standard output. The block counts are of IK blocks, 

unless the environment variable posixly_correct isset, in which case512- byte blocks are used. 


OPERATORS 


Listed in order of decreasing precedence: 



Force precedence. 

True if expr is false. 

Same as! expr. 

And (implied); expr 2 is not evaluated if expr 1 isfalse. 

Sameasexprl expr 2. 

Sameas exprl expr2. 

Or; expr 2 isnot evaluated if expri istrue. 

Sameasexprl -0 expr2. 

List; both expri and expr 2 are always evaluated. The valueofexpri 
is the value of ex pr 2. 


is discarded; the value of the list 


SEE ALSO 

locate(lL), iocatedb( 5 L), updatedb(lL), xargs(lL) Finding Files (online in info, or printed) 
GNU FileUtilities 


fitstopnm 

fitstopnm— Convert a FITS file into a portable anymap 

SYNOPSIS 

fitstopnm [-image N][-noraw][-scanmax][-printmax][-min f][-max f][FI TSf i I e] 

DESCRIPTION 

Reads a FITS file asinput. Produces a portable pixmap if the FITS file consists of 3 image planes (naxis = 3andNAxiS3 = 3), 
a portable graymap if the FITS file consists of 2 image planes (naxis = 2), or whenever the -image flag is specified. The 
results may need to be flipped top for bottom; if so, just pipe the output through pnmfiip -tb. 








fold 


FI 


OPTIONS 

The -image option isfor FITS fileswith three axes. Theassumption is that thethird axis isfor multiple images, and this 
option lets you select which one you want. 

Flags -min and -max can be used to override the min and max values as read from the FITS header or the image data if no 
dat am in andDATAMAx keywords are found. Flag -scanmax can be used to force the program to scan the data even when datamin 
and datamax are found in the header. If -printmax isspecified, the program will just print the min and max values and quit. 
Flag -noraw can be used to force the program to produce an ASCII portable anymap. 

The program will tell what kind of anymap is writing. All flags can be abbreviated to their shortest unique prefix. 

REFERENCES 

FITS stands for Flexible I mage Transport System. A full description can be found in Astronomy& AirophysicsSupplement 
Series44 (1981), page 363. 

SEE ALSO 

pnmtofits(l), pgm( 5 ), pnmflip(l) 

AUTHOR 

Copyright © 1989 byjef Poskanzer, with modifications by Daniel Briggs (dbri9gs@nra0.edu) and Alberto Accomazzi 
(alberto@cfa.harvard.edu) 

20 September 1989 

f mt 

fmt— Adjust line-length for paragraphs of text 

SYNOPSIS 

DESCRIPTION 

fmt is a simple text formatter. It inserts or deletes newlines, as necessary, to make all lines in a paragraph be approximately the 
same width. It preserves indentation and word spacing. 

The default line width is 72 characters You can override this with the -width flag. If you don't name any files on the 
command line, then fmt will read from stdin. 

It is typically used from within vito adjust the line breaks in a single paragraph. To do this move the cursor to the top of 
the paragraph, type igfmt, and press Return. 

AUTHOR 

Steve Kirkendall (kirkenda@cs.pdx.edu) 

fold 

fold- W rap each input line to fit in specified width 

SYNOPSIS 

fold [-bs] [-w width] [-bytes] [-spaces] [-width=wi dt h ] [-help] 

[-version] [file...] 
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DESCRIPTION 

This manual page documents the GN U version of fold, fold prints the specified files, or the standard input when no files are 
given or the filename- is encountered, on the standard output. It breaks long linesinto multiple shorter lines by inserting a 
newline at column 80. It counts screen columns, so tab characters usually take more than one column, backspace characters 
decrease the column count, and carriage return characters set the column count back to zero. 

OPTIONS 

-s, -spaces 

-w, -width width 
— help 

GNU Text Utilities 

free 

free- Display amount of free and used memory in the system 

SYNOPSIS 

free [-b | -k | -in] [- 0 ] J'-s delay] [-t] 

DESCRIPTION 

free displays the total amount of free and used physical and a/vap memory in the system, as well as the shared memory and 
buffers used by the kernel. 

OPTIONS 

The -b switch displays the amount of memory in bytes; the -k switch (set by default) displays it in kilobytes; the -m switch 
displays it in megabytes 

The -t switch displaysa line containing thetotals 

The -0 switch disables the display of a "buffer adjusted" line U nless specified free subtracts/adds buffer memory from/to the 
used/free memory reports (respectively!). 

The -s switch activates continuous polling delay seconds apart. You may actually specify any floating point number for 
delay, usieep(3) is used for microsecond resolution delaytimes. 

FILES 

/proc/meminfo M emory information 

SEE ALSO 

ps(1), top(l) 

AUTHORS 

Brian Edmonds 

Cohesive Systems, 20 M arch 1993 


Count bytes rather than columns, so that tabs, backspaces, and carriage returns are each counted as 
taking up one column, just like other characters. 

Break at word boundaries If the line contains any blanks, the line is broken after the last blank that 
falls within the maximum line length. If there are no blanks the line is broken at the maximum 
line length, as usual. 

Use a maximum line length of width columns instead of 80. 

Print a usage message and exit with a nonzero status. 

Print version information on standard output then exit. 
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fsinfo— x font server information utility 

SYNOPSIS 

fsinfo [-server server name] 

DESCRIPTION 

fsinfo isa utility for displaying information about an X font server. It is used to examinethecapabilitiesof a server, the 
predefined values for various parameters used in communicating between clients and the server, and the font catalogues and 
alternate servers that are avai lable. 

EXAMPLE 

Thefollowing isa sample produced by fsinfo. 

name of server: hansen:7100 
version number: 1 

vendor string: Font Server Prototype 
vendor release number: 17 

maximum request size: 16384 longwords (65536 bytes) 

number of catalogues: 1 

all 

Number of alternate servers: 2 
#0 hansen:7101 
#1 hansen:7102 
number of extensions: 0 

ENVIRONMENT 

fontserver T o get the default fontserver 

SEE ALSO 

xfs(l), fslsfonts(l) 

AUTHOR 

D ave Lemke (N etwork C omputing D evices, I nc.) 

X Version 11 Release6 

fslsfonts 

fsisfonts— List fonts served by X fontserver 

SYNOPSIS 

fslsfonts [-options ...] [-fn pattern] 

DESCRIPTION 

fslsfonts lists the fonts that match the given pattern. The wildcard character * may be used to match any sequence of 
characters (including none), and ? to match any single character. If no pattern is given, * isassumed. 

The* and ? characters must be quoted to prevent them from being expanded by the shell. 

OPTIONS 

-server host: por t Thisoption specifiesthe X font server to contact. 

-l Lists some attributes of thefont on one line in addition to its name 
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Lists font propertiesin addition to -1 output. 

Supported for compatibility with xisfonts, but output isthesameasfor -11. 

This option indicates that long listings should also print the minimum and maximum bounds of 
each font. 

This option indicates that listings should use multiple columns This isthe same as-n 0. 

This option indicates that listings should use a single column. This isthe same as-n 1. 

Thisoption specifies the width in characters that should be used in figuring out how many 
columns to print. The default is 79. 

Thisoption specifies the number of columnsto use in displaying the output. The default iso, 
which will attempt to fit as many columns of font names into the number of character specified by 
-w width. 

Thisoption indicates that the output should be left unsorted. 

SEE ALSO 

xfs(l), showfont(l), xlsfonts(l) 

ENVIRONMENT 

fontserver T o get the default host and port to use 

BUGS 

Doing fsisfonts -1 can tie up your server for a very longtime. This is really a bug with single-threaded nonpreemptable 
servers, not with this program. 

AUTHOR 

D ave Lemke (N etwork C omputing D evices, I nc.) 

X Version 11 Release 6 1 

fstobdf 

fstobdf— Generate BD F font from X font server 

SYNOPSIS 

fstobdf [ -server server ] -fn fontname 

DESCRIPTION 

The fstobdf program reads a font from a font server and prints a BD F file on the standard output that may be used to 
recreate the font. This is useful in testing servers, debugging font metrics, and reproducing lost BDF files 

OPTIONS 

-server server name Thisoption specifies the server from which the font should be read. 

-fn fontname Thisoption specifies the font for which a BDF file should be generated. 

ENVIRONMENT 

fontserver D efault server to use 

SEE ALSO 

xfs(l), bdftopcf(l), fslsfonts(l) 
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AUTHOR 

Olaf Brandt (Network Computing Devices), DaveLemke(Network Computing De/ices), Jim Fulton (M IT X Consortium) 
X Version 11 Release6 

fstopgm 

fstopgm- Convert aU senix FaceSaver file into a portable graymap 

SYNOPSIS 

fstopgm [f sfiI e ] 

DESCRIPTION 

Reads a U senix FaceSaver file as input. Produces a portable graymap asoutput. 

FaceSaver files sometimes have rectangular pixels Although fstopgm won't rescale them into square pixelsfor you, it will give 
you the precise pnmscale command that will do the job. Because of this, reading a F aceSaver image is a two-step process. 
First you do 

fstopgm > /dev/null 

This will tell you whether you need to use pnmscale. Then use one of the following pipelines: 

fstopgm | pgmnorm 

fstopgm | pnmscale -whatever ] pgmnorm 

To go to P B M, you want something more like oneof these: 

fstopgm | pnmenlarge 3 | pgmnorm | pgmtopbm 

fstopgm | pnmenlarge 3 | pnmscale <whatever> | pgmnorm | pgmtopbm 

You want to enlarge when going to a bitmap because otherwise you lose information; but enlarging by more than 3 does not 
look good. 

FaceSaver is a registered trademark of M dtron Computerware Ltd. of Oakland, CA. 

SEE ALSO 

pgmtofs(l), pgm( 5 ), pgmnorm(l), pnmenlarge(l), pnmscale(l), pgmtopbm(l) 

AUTHOR 

Copyright © 1989 byJef Poskanzer 
6 April 1989 

ftp 

ftp- ARPAndt file transfer program 

SYNOPSIS 

ftp [-V] [-d] [-1] [-nj [ -g] [host ] 

DESCRIPTION 

ftp istheuser interface to the ARPAnet standard FileT ransfer Protocol. The program allows a user to transfer files to and 
from a remote network site. 

Options may be specified atthecommand line, or to the command interpreter. 
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-v Verbose option forces ftp to show all responses from the remote server, as well as 

report on data transfer statistics 

-n Restrainsftp from attempting auto-login upon initial connection. If auto-login is 

enabled, ftp will check the (see below) file in the user's home directory for an entry 
describing an account on the remote machine. If no entry exists, ftp will prompt for 
theremotemachinelogin name(default is the user identity on thelocal machine), 
and, if necessary, prompt for a password and an account with which to login. 

-i T urns off interactive prompting during multiple file transfers 

-d Enables debugging. 

-g Disablesfilenameglobbing. 

The client host with which ftp isto communicate may be specified on the command line If this is done, ftp will immedi¬ 
ately attempt to establish a connection to an FTP server on that host; otherwise, ftp will enter its command interpreter and 
await instructions from the user. W hen ftp is awaiting commands from the user, the prompt 
ft P > 

is provided to the user. T hefollowing commands are recognized by ftp: 

i [command] [args] Invoke an interactive shell on the local machine. If there are arguments, thefirst is 

taken to be a command to execute directly, with the rest of the arguments as its 
arguments. 

$ macro-name [args] Execute the macro mac r o-na me that wasdefined with themacdef command. 

Arguments are passed to the macro unglobbed. 

account [passwd ] Supply a supplemental password required by a remote system for access to resources 

oncea login has been successfully completed. If no argument is included, the user 
will be prompted for an account password in a nonechoing input mode, 
append i oca i -f i i e [r emote - f i i e ] Append a local file to a file on the remote machine. If remote-f i i e is left unspecified, 
thelocal filename isused in naming the remote file after being altered by any ntrans 
or nmap setting. File transfer uses the current settings for type, format, mode, and 



Set the file transfer type to network ASCII. This is the default type. 

Arrange that a bell be sounded after each file transfer command iscompleted. 

Set the file transfer type to support binary image transfer. 

Terminate the FTP session with the remote server and exit ftp. An end of file will 
also terminate the session and exit. 

Toggle remote computer filenamecase mapping during mget commands. W hen case 
is on (default is off), remote computer filenames with all letters in upper case are 
written in the local directory with the letters mapped to lowercase. 

Change the working directory on the remote machine to remote- di rectory. 

C hange the remote machine working directory to the parent of the current remote 
machine working directory. 

C hange the permission modes of the fi le f i i e - n a me on the remote system to mo d e . 
Terminate the FTP session with the remote server, and return to the command 
interpreter. Any defined macros are erased. 

Toggle carriage return stripping during ASC 11 type file retrieval. Records are 
denoted by a carriage return/iinefeed sequence during ASCII type file transfer. 
When cr ison (the default), carriage returnsare stripped from this sequence to 
conform with the UN IX single linefeed record delimiter. Recordson non-UN IX 
remote systems may contain single linefeeds; when an ASC 11 type transfer is made, 
these linefeeds may be distinguished from a record delimiter only when cr isoff. 

D elete the file r e mo t e - f i i e on the remote machi ne. 
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debug [debug-val ue ] 


dir [remote-di rectory] [local-file] 


help [command 
idle [seconds 
led [director 
Is [remote-di 


maedef macro - name 


mdelete [remote-fi I es] 


Toggle debugging mode. If an optional debug-vai ue isspecified, it is used to set the 
debugging level. W hen debugging is on, ftp prints each command sent to the 
remote machine preceded by the string ->. 

Print a listing of thedirectory contents in thedirectory, remote-di rectory, and, 
optionally, placing the output in i ocai-file. If interactive prompting ison, ftp will 
prompt the user to verify that the last argument is indeed the target local file for 
receiving dir output. If no directory isspecified, the current working directory on 
the remote machine is used. If no local file isspecified, or i ocai - f i i e is-, output 
comes to theterminal. 

A synonym for close. 

Set the file transfer form to f o r ma t . T he default f o r ma t is file. 

Retrieve the remote-fi i e and store it on the local machine. If the local filename is 
not specified, it is given the same name it has on the remote machine subject to 
alteration by thecurrent case, ntrans, and nmap settings The current settings for 
type, form, mode, and structure areused whiletransferring thefile 
Toggle filename expansion for mdelete, mget, and input. If globbing is turned off with 
giob, the filename arguments are taken literally and not expanded. Globbing for mput 
is done as in esh i. For mdelete and mget, each remote filename is expanded 
separately on the remote machine and the lists are not merged. Expansion of a 
directory name is likely to be different from expansion of the nameof an ordinary 
file: the exact result depends on the foreign operating system and FT P server, and 
can be previewed by doing mis remote-files N ote: mget and mput are not meant to 
transfer entiredirectorysubtreesof files That can bedoneby transferring a tar i 
archive of the subtree (in binary mode). 

Toggle hash-sign (#) printing for each data block transferred. T he size of a data block 
is 1024 bytes 

Print an informative message about the meaning of command. If no argument is given, 
ftp prints a list of the known commands. 

Set the inactivity timer on the remoteserver to seconds seconds. If seconds is 
omitted, thecurrent inactivity timer is printed. 

C hange the working directory on the local machine. If no directory is specified, the 
user's home directory is used. 

Print a listing of the contents of a directory on the remote machine T he listi ng 
includes any system-dependent information that the server chooses to include; for 
example, most systems will produce output from the command is 1. (See also 
niist.) If remote-di rectory is left unspecified, thecurrent working directory isused. 

If interactive prompting ison, ftp will prompt the user to verify that the last 
argument is indeed the target local file for receiving is output. If no local file is 
specified, or if i ocai -f i i e is-, the output is sent to theterminal. 

Define a macro. Subsequent lines are stored as the macro macro- name; a null line 
(consecutive newline characters in a file or carriage returns from theterminal) 
terminates macro input mode. There isa limit of 16 macros and 4096 total 
characters in all defined macros. M acros remain defined until a close command is 
executed. T he macro processor interprets $ and \ as special characters A $ followed 
by a number (or numbers) is replaced by the corresponding argument on the macro 
invocation command line A $ followed by an i signals that macro processor that the 
executing macro isto be looped. 0 n thefirst pass$i is replaced by thefirst argument 
on the macro invocation command line on the second pass it is replaced by the 
second argument, and so on. A \ followed by any character is replaced by that 
character. Usethe\to prevent special treatment of the$. 

Delete the remote-fi i es on the remote machine 




Like dir, except multiple remote files may be specified. If interactive prompting is 
on, ftp will prompt the user to verify that the last argument is indeed the target local 
file for receiving mdir output. 

Expand ther emot e-files on the remote machine and do a get for each filename thus 
produced. See giob for details on thefilename expansion. Resulting filenames will 
then be processed according to case, ntrans, and nmap settings. Files are transferred 
into the local working directory, which can be changed with led directory; new local 
directories can be created with imkdir directory. 

M ake a directory on the remote machine. 

Like mist, except multiple remote files may be specified, and theiocai-me must 
be specified. If interactive prompting ison, ftp will prompt the user to verify that 
the last argument isindeed the target local file for receiving mis output. 

Set the file transfer mode to mo d e ■ n a me. T he default mode is stream mode. 

Show the last modification time of the file on the remote machine. 

Expand wildcards in the list of local files given as arguments and do a put for each 
filein the resulting list. See giob for details of filename expansion. Resulting 
filenames will then be processed according to ntrans and nmap settings 
G et the file only if the modification time of the remote file is more recent that the 
fileon the current system. If the file does not exist on the current system, the remote 
file is considered newer. Otherwise, this command is identical to get. 

Print a list of the files in a directory on the remote machine. If remote- di rectory is 
left unspecified, the current working directory is used. If interactive prompting ison, 
ftp will prompt the user to verify that the last argument is indeed the target local file 
for receiving niist output. If no local file is specified, or if i oca i - f i i e is-, the 
output is sent to theterminal. 

Set or unset thefilename mapping mechanism. If no arguments are specified, the 
filename mapping mechanism isunset. If arguments are specified, remote filenames 
are mapped during input commands and put commands issued without a specified 
remote target filename. If arguments are specified, local filenames are mapped during 
mget commands and get commands issued without a specified local target filename. 
This command is useful when connecting to a non-UN IX remote computer with 
different file naming conventions or practices The mapping follows the pattern set 
by inpattern and outpattern. inpattern is a template for incoming filenames (which 
may have already been processed according to the ntrans and case settings). Variable 
templatingisaccomplished by including the sequences $ 1 , $ 2 ,..., $9 in inpattern. 

U se \ to prevent this special treatment of the $ character. Al I other characters are 
treated literally, and are used to ddterrninethenmap inpattern variable values. For 
example, given inpattern $1 .$2 and the remote filename mydata. data, $1 would have 
the value mydata, and $2 would have the value "data". The outpattern determines the 
resulting mapped filename. The sequences $ 1 , $ 2 ,...., $9 are replaced by any value 
resulting from the inpattern template. The sequence $0 is replaced by the original 
filename. Additionally, the sequence seqi, seq2 is replaced by seqi ifseqi isnota 
null string; otherwise, it is replaced by seq 2 . For example the command nmap 
$1 .$ 2 . $3 [$1 , $ 2 ]. [$ 2 ,t iie] would yield the output filename mytiie.data for 
input filenames my-file. data and myfile.data.old, myfile.file for the input 
fi lename my -me, and mytHe. myfile for the i nput filename. myf He . Spaces may be 
included in outpattern, as in the example: nmap $1 sed "s / *$//" > $i.Usethe\ 
character to prevent special treatment of the $,[,[, and , characters 
Set or unset thefilename character translation mechanism. If no arguments are 
specified, the filename character translation mechanism isunset. If arguments are 
specified, charactersin remote filenames are translated during mput commands and 
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open host [port] 


prompt 


proxy ftp-command 


quote ar gl arg2 ... 


recv r emot e-f i I e [I oca I ■ f i I e ] 


reget r emot e- f i I e [I oca I • f i I e ] 


remotehelp [command-name] 
remotestatus [file- name ] 
rename [from] [to] 


put commands issued without a specified remote target filename. If arguments are 
specified, characters in local filenames are translated during mget commands and get 
commands issued without a specified local target filename This command is useful 
when connecting to a non-U NIX remote computer with different file naming 
conventions or practices Characters in a filename matching a character in i nchars 
are replaced with the corresponding character in out chars . If the character's position 
in i nchars is longer than the length of out chars, the character is deleted from the 
filename. 

Establish a connection to the specified host FT P server. An optional port number 
may be supplied, in which case ftp will attempt to contact an FT P server at that 
port. If the auto-login option ison (default), ftp will also attempt to automatically 
log the user in to the FTP server (see below). 

Toggle interactive prompting. I nteracti ve prompting occurs during multiple file 
transfers to allow the user to selectively retrieve or store files If prompting is turned 
off (default ison), any mget or input will transfer all files and any mdeiete will delete 
all files. 

Execute an ftp command on asecondary control connection. This command allows 
simultaneous connection to two remote FTP servers for transferring files between 
thetwo servers Thefirst proxy command should bean open, to establish the 
secondary control connection. Enter the command "proxy ?■ to see other ftp 
commands executable on the secondary connection. The following commands 
behave differently when prefaced by proxy :, open will not define new macros during 
the auto-login process close will not erase existing macro definitions get and mget 
transfer files from the host on the primary control connection to the host on the 
secondary control connection, and put, input, and append transfer files from the host 
on the secondary control connection to the host on the primary control connection. 
Third-party file transfers depend upon support of the FT P protocol pasv command 
by the server on the secondary control connection. 

Store a local file on the remote machine If r emot e-f i i e is left unspecified, the local 
filename is used after processing according to any ntrans or nmap settings in naming 
the remote file File transfer uses the current settings for type, format, mode, and 
structure. 

Print the name of the current working directory on the remote machine. 

A synonym for bye. 

T he arguments specified are sent, verbati m, to the remote FTP server. 

A synonym forget. 

Reget acts like get, except that if i oc ai - f i i e exists and is smaller than remot e-f i i e, 
local - fi le ispresumed to be a partially transferred copy of r emot e-f i i e and the 
transfer is continued from the apparent point of failure. This command is useful 
when transferring very large files over networks that are prone to dropping 
connections. 

Request help from the remote FTP server. If acommand-name isspecified, it issupplied 
to the server as well. 

With no arguments, show status of remote machine. If fi i e-name isspecified, show 

status oft i e-name on remote machine 

Renamethefilefrom on the remote machine to thefile t o. 

Clear reply queue. Thiscommand resynchronizes command/reply sequencing with 
the remote FT P server. Resynchronization may be necessary following a violation of 
the FT P protocol by the remote server. 

Restart the immediately following get or put at the indicated marker. On U N IX 
systems, ma r k e r is usually a byte offset i nto the fi le. 
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rmdir di rectory - name 




site a r g1 a r g 2... 


struct [struct-name] 
sunique 


system 


type [type-name ] 
umask [newmask] 


user user- name [passi 


p d ] [account ] 


verbose 


D elete a directory on the remote machine 

Toggle storing of files on thelocal system with unique filenames. If afile already 
exists with a nameequal to the target local filename for a get or mget command, a .1 
isappended to the name. If the resulting namematches another existing file a .2 is 
appended to the original name If this process continues up to .99, an error message 
is printed, and the transfer does not take place. The generated unique filename will 
be reported. N otethat runique will not affect local files generated from a shell 
command. The default value is oft. 

A synonym for put. 

Toggle the use of port commands. By default, ftp will attempt to use a port 
command when establishing a connection for each data transfer. T he use of port 
commandscan prevent delays when performing multiple file transfers. If the port 
command fails, ftp will use the default data port. When the use of port commands is 
disabled, no attempt will be made to use port commands for each data transfer. T his 
is useful for certain FTP implementations which do ignore port commands but, 
incorrectly, indicate they've been accepted. 

The arguments specified are sent, verbati m, to the remote FT P server as a site 
command. 

Return size of file-name on remote machine 
Show the current status of ftp. 

Set the file transfer structure to s t r u c t ■ n a me. By default stream structure is used. 
Toggle storing of files on remote machine under unique filenames. Remote FTP 
server must support ftp protocol stou command for successful completion. The 
remote server will report unique name Default value is off. 

Show the type of operating system running on the remote machine 
Set the file transfer type to that needed to talk to T E N EX machines. 

Toggle packet tracing. 

Set the file transfer type to t y pe-na me. If no type is specified, the current type is 
printed. Thedefault type is network ascii. 

Set the default umask on the remote server to newmas k. If newmas k is omitted, the 
current umask is printed. 

Identify yourself to the remote FTP server. If the password is not specified and the 
server requires it, ftp will prompt the user for it (after disabling local echo). If an 
account field is not specified, and the FTP server requires it, the user will be 
prompted for it. If an account field is specified, an account command will be relayed 
to the remote server after the login sequence is completed if the remote server did 
not require it for logging in. Unless ftp is invoked with auto-login disabled, this 
process is done automatically on initial connection to the FTP server. 

T oggle verbose mode. I n verbose mode, all responses from the FT P server are 
displayed to the user. In addition, if verbose is on, when a file transfer completes, 
statistics regarding the efficiency of the transfer are reported. By default, verbose is 


? [command] A Synonym for help. 

Command arguments which have embedded spaces may be quoted with quotation marks ("). 

ABORTING A FILE TRANSFER 

To abort a file transfer, use the terminal interrupt key (usually Ctrl-C). Sending transfers will be immediately halted. 
Receiving transfers will be halted by sending an FTP protocol abor command to the remote server, and discarding any 
further data received. The speed at which this is accomplished depends upon the remote server's support for abor processing. 
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If the remote server does not support the abor command, an ftp> prompt will not appear until the remote server has 
completed sending the requested file. 

Theterminal interrupt key sequence will be ignored when ftp has completed any local processing and is awaiting a reply 
from the remote server. A long delay in this mode may result from the abor processing described earlier in this section, or 
from unexpected behavior by the remote server, including violations of the FTP protocol. If the delay results from unex¬ 
pected remote server behavior, the local ftp program must be killed by hand. 

FILE NAMING CONVENTIONS 

Files specified as arguments to ftp commands are processed according to the following rules: 

If the filename - is specified, the stdtn (for reading) or stdout (for writing) is used. 

If the first character of the filename is/, the remainder of the argument is interpreted as a shell command, ftp then forks a 
shell, using popen 3 with the argument supplied, and reads (writes) from the stdout (stdtn). If the shell command includes 
spaces, the argument must be quoted; for example, is -it. A particularly useful example of this mechanism is: dir more. 
Failing the preceding checks, if "globbing" isenabled, local filenames are expanded according to the rules used in thecsh 1; 
c.f. the giob command. If the ftp command expects a single local file (for example put), only the first filename generated by 
the "globbing" operation is used. 

For mget commands and get commands with unspecified local filenames, the local filename isthe remote filename which 
may be altered by a case, ntrans, or nmap setting. The resulting filename may then be altered ifrunique ison. 

For mput commands and put commands with unspecified remote filenames, the remote filename is the local filename, which 
may be altered by an ntrans or nmap setting. The resulting filename may then be altered by the remote server if sunique ison. 

FILE TRANSFER PARAMETERS 

T he FT P specification specifies many parameters that may affect a file transfer. T he type may be one of ASC11, image 
(binary), ebcdic, and local byte size (for PD P Ns-lOsand PDP Ns-20s mostly), ftp supports the ASC 11 and image types of 
file transfer, plus local byte size 8 for tenex mode transfers 

ftp supports only the default values for the remaining file transfer parameters: mode, form, and struct. 


THE. netrc FILE 


The file contains login and initialization information used by the auto-login process. It residesin the user's home directory. 
The following tokens are recognized; they may be separated by spaces, tabs, or newlines: 


machine name 


default 


login name 
password string 


account string 


Identify a remote machine name The auto-login process searches the file for a machine token that 
matches the remote machine specified on the ftp command line or as an open command argument. 
W hen a match is made, the subsequent tokens are processed, stopping when the end of file is 
reached or another machine or a default token is encountered. 

This isthe same as machine nameexcept that default matches any name. There can be only one 
default token, and it must be after all machinetokens This is normally used asdef aui t login 
anonymous password user @s i t e, thereby giving the user automatic anonymous ftp login to machines 
not specified. This can be overridden by using the -n flag to disable auto-login. 

Identify a user on the remote machine If thistoken ispresent, the auto-login process will initiatea 
login using the specified name. 

Supply a password. If thistoken ispresent, the auto-login process will supply the specified string if 
the remote server requires a password as part of the login process N ote that if this token is present 
in thefilefor any user other than anonymous ftp will abort the auto-login process if the is readable 
by anyone besides the user. 

Supply an additional account password. If thistoken ispresent, theauto-login process will supply 
the specified string if the remote server requires an additional account password, or the auto-login 
process will initiate an acct command if it does not. 
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macdef name D efine a macro. This token functions like the ftp macdef command functions. A macro is defined 

with the specified name; its contents begin with the next line and continue until a null line 
(consecutive newline characters) is encountered. Ifamacro named imt isdefined, it ^automati¬ 
cally executed asthelast step in theauto-login process 

ENVIRONMENT 

ftp utilizesthefollowing environment variables 

home For default location of a file, if one exists 

shell For default shell 

SEE ALSO 

ftpd(8) 

HISTORY 

The ftp command appeared in BSD 4.2. 

BUGS 

Correct execution of many commands depends upon proper behavior by the remote server. 

An error in the treatment of carriage returns in the BSD 4.2 ASCI l-modetransfer code has been corrected. This correction 
may result in incorrect transfers of binary files to and from BSD 4.2 servers using the ASCI I type. Avoid this problem by 
using the binary image type 
BSD 4.2, 30 July 1991 

fuser 

fuser— Identify processes using files 

SYNOPSIS 

fuser [-a|-s] [-s i gna I ][-kmuv] filename ... [-][-si gnal ][-kmuv] f i I ename ... 
fuser [-1] 

DESCRIPTION 

fuser displays the PI Dsof processes using the specified files or file systems In the default display mode each filename is 
followed by a letter denoting the type of access 
c Current directory, 

e Executable being run. 

f Open file f isomitted in default display mode, 

r Root directory, 

m mmap'ed fileor shared library. 

fuser returns a nonzero return code if none of the specified files is accessed or in case of a fatal error. If at least one access has 
been found, fuser returns zero. 

OPTIONS 

-a Show all files specified on the command line. By default, only files that are accessed by at least one process 

are shown. 

-k Kill processes accessing thefile Unless changed with -signal, sigkill issent. A fuser 

itself, but may kill other fuser processes. 


process never kills 



u List all known signal names 

-m f i i ename specifies a file on amounted filesystem or a block devicethat is mounted. All processes accessing 

fi les on that file system are listed. If a directory file is specified, it is automatically changed to filename/. to 
use any file system that might be mounted on that directory. 

-s Silent operation, -a, -u, and -v are ignored in this mode. 

-si gnai Use the specified signal instead of sigkill when killing processes. Signals can be specified either by name 

(for example, -hup) or by number (for example, -i). 

-u Append the username of the process owner to each PID. 

-v Verbose mode. Processes are shown in a ps-like style. Thefidds pid, user, and command aresimilarto ps. 

access shows how the process accesses thefile. 

Reset all options and set the signal back to sigkill. 

FILES 

/proc Location of the proc file system 

EXAMPLES 

fuser -km /home kills all processes accessing thefile system / home in anyway. 

In this example: 

if fuser -s /dev/ttySI; then else something 

fi invokes something if no other process is using /dev/ttysi. 

RESTRICTIONS 

Processesaccessingthesame file or filesystem several times in the same way are only shown once. 

AUTHOR 

W erner Almesberger (<aimesber@di. epf 1. ch>u) 

SEE ALSO 

kill(l), killall(l), ps(l), kill(2) 

Linux, 11 October 1994 

g++ 

g ++-GNU project C++Compiler 

SYNOPSIS 

DESCRIPTION 

TheC and C++compilers are integrated; g++ isa script to call gcc with options to recognizeC++. gcc processes in put files 
through oneor more of four stages: preprocessing, compilation, assembly, and linking. Thisman pagecontainsfull 
descriptionsfor only C ++ specific aspects of the compiler, though it also contains summaries of some general-purpose 
options For a fuller explanation of the compiler, see gcc(l). 

C++source files use one of thesuffixes .c, .cc, .cxx, .cpp, or.c++; preprocessed C++ files use the suffix .n. 

OPTIONS 

There are many command-line options, including options to control details of optimization, warnings, and codegeneration, 
which are common to both gcc and g++. For full information on all options, see gcc(l). 
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Options must be separate -dr is quite different from -d -r. 

M ost -f and -w options have two contrary forms: -frame and -fno-rame (or-wname and -wno-rame). Only the nondefault 
forms are shown here. 


-fall-virtual 


-felide-constructors 


-fenum-int-equiv 


-fexternal-templates 


-fmemoize-lookups-fsave-memorized 


Compile or assemble the source files, but do not link. The compiler output isan 
object file corresponding to each source file. 

D efine macro macro with the string i as its definition. 

Define macro macro asdefn. 

Stop after the preprocessing stage; do not run the compiler proper. The output is 
preprocessed source code, which is sent to the standard output. 

Treatall possible member functionsas virtual, implicitly. All member functions 
(except for constructor functions and new or delete member operators) are treated as 
virtual functions of the class where they appear. 

This does not mean that all callsto these member functions will be made through 
the internal table of virtual functions U nder some circumstances the compiler can 
ddterminethatacall to agiven virtual function can be made directly; in these cases 
thecalls are direct in any case 

Permit the use of $ in identifiers. T raditional C allowed the character $ to form part 
of identifiers by default, GN U C also allows this However, AN SI C forbids $ in 
identifiers, and G N U C -H-also forbids it by default on most platforms (though on 
some platforms it's enabled by default for G N U C++as well). 

Use this option to instruct the compiler to be smarter about when it can elide 
constructors. W ithout this flag, GNU C ++ and cf rant both generate effectively the 
same code for 
A foo (); 

A x (foo ()); // x initialized by 'foo ()', no ctor called 
A y = foo (); // call to 'foo ()' heads to temporary, // y is initial¬ 
ized from the temporary. 

Note the difference. With thisflag, GN U C++initializesy directly from the call to 
food without going through a temporary. 

Normally GN U C++allows conversion of enum to int, but not the other way 
around. Use this option if you wantGNU C++to allow conversion of int to enum as 
well. 

Produce smaller code for template declarations, by generating only a single copy of 
each tempi ate function where it isdefined. T o usethisoption successfully, you must 
also mark all files that use templates with either #pragma implementation (the 
definition) or #pragma interface (declarations). 

When your code is compiled with -fexternai-tempiates, all template instantiations 
are external. You must arrange for all necessary instanti ationsto appear in the 
implementation file; you can do this with atypedef that references each instantiation 
needed. Conversely, when you compile using the default option -fno- external- 
templates, all template instantiations are explicitly internal. 

Do not output global initializations (such as C++constructors and destructors) in 
the form used bytheGNU linker (on systems where theGN U linker is the standard 
method of handling them). Usethisoption when you want to useanon-GN U 
linker, which also requires using thecoiiect 2 program to make sure the system 
linker includes constructors and destructors (coiiect 2 isincluded in theGN U CC 
distribution.) For systems which must use coiiect 2 , the compiler driver gcc is 
configured to do this automatically. 

These flags are used to gdt the compiler to compile programs faster using heuristics 
They are not on by default since they are only effective about half the time The 
other half of the time programs compile more slowly (and take more memory). 
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-fno-default-inline 


-fno-strict-prototype 


-fhandle-signatures- 
fno-handle-signatures 


The first time the compiler must build a call to a member function (or reference to a 
data member), it must (1) determine whether the class implements member 
functions of that name; (2) resolve which member function to call (which involves 
figuring out what sorts of type conversions need to be made); and (3) check the 
visibility of the member function to the caller. All of this adds up to slower 
compilation. N ormally, the second time a call is made to that member function (or 
reference to that data member), it must go through the same lengthy process again. 
This meansthat code like this: 

makes six passes through all three steps. By using a software cache, a "hit" signifi¬ 
cantly reduces this cost. U nfortunately, using the cache introduces another layer of 
mechanisms which must be implemented, and so incurs its own overhead. - 
fmemorize- lookups enables the software cache 

Because access privileges (visibility) to members and member functions may differ 
from one function context to the next, g++ may need to flush the cache With the- 
fmemoize-iookups flag, the cache is flushed after every function that is compiled. The 
-fsave-memorized flag enables the same software cache, but when the compiler 
determines that the context of the last function compiled would yield the same 
access privileges of the next function to compile, it preserves the cache T his is most 
helpful when defining many member functions for the same class: with the 
exception of member functions which are friends of other classes, each member 
function has exactly the same access privileges as every other, and the cache need not 
be flushed. 

D o not make member functions inline by default merely because they are defined 
inside the class scope. Otherwise when you specify-o, member functions defined 
inside class scope are compiled inline by default; that is, you don't need to add 
inline in front of the member function name 

Consider the declaration int too; (). In C++, this means that the function foo takes 
no arguments. In AN SI C, this is declared int too (void);. With the flag -fno- 
strict-prototype, declaring functions with no arguments is equivalent to declaring 
its argument list to be untyped, that is, int food; isequivalent to saying int too 
(...); .-fnonnuii-objects. Normally, GNU C++makes conservative assumptions 
about objects reached through references. For example thecompiler must check that 
a is not null in code like the following: 

a.f (2); 

C hecking that references of this sort have non-null values requires extra code, 
however, and it is unnecessary for many programs. You can use -f nonnuii-obj ects to 
omit the checks for null, if your program doesn't require the default checking. 

These options control the recognition of the signature and sigof constructs for 
specifying abstract types By default, these constructs are not recognized. 

The incorporation of user-defined free store management into C ++has made 
assignment to this an anachronism. Therefore, by default GNU C++treats the type 
of this in a member function of classX to bex *const. In other words itisillegal to 
assign to this within a class member function. Flowever, for backwards compatibil¬ 
ity, you can invoke the old behavior by using -fthis-is-variabie. 

Produce debugging information in the operating system's native format (for D BX or 
SD B or DWARF). GDB also can work with this debugging information. On most 
systems that use D BX format, -g enables use of extra debugging information that 
only GDB can use 

Unlike most other C compilersGNU CC allows you to use-g with -o.The 
shortcuts taken by optimized code may occasionally produce surprising results some 
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-nostdinc++ 

-0 




-Wall 

-Wenum-clash 
-Woverloaded-virtual 


variables you declared may not exist at all; flow of control may briefly move where 
you did not expect it; some statements may not be executed because they compute 
constant results or their values were already at hand; some statements may execute in 
different places because they were moved out of loops. 

N evertheless it proves possible to debug optimized output. This makes it reasonable 
to use the optimizer for programs that might have bugs. 

Append directory d i r to the list of directories searched for include files 
Add directory d i r to the list of directories to be searched for-i. 

Use the library named library when linking. (C++ programs often require -ig++ for 
successful linking.) 

Do not search the standard system directories for header files. Only the directories 
you have specified with -i options (and the current directory, if appropriate) are 
searched. 

D o not search for header files in the standard directories specific to C ++, but do still 
search the other standard directories (Thisoption isused when building iibg++.) 

0 ptimize 0 ptimizing compilation takes somewhat more time, and a lot more 
memory for a large function. 

Place output in filet i i e. 

Stop after the stage of compilation proper; do not assemble. The output isan 
assembler code file for each nonassembler input file specified. 

Attempt to support some aspects of traditional C compilers. Specifically, for both C 
and C++programs: 

In the preprocessor, comments convert to nothing at all, rather than to aspace This 
allows traditional token concatenation. 

In the preprocessor, macro arguments are recognized within string constants in a 
macro definition (and their values are stringified, though without additional quote 
marks, when they appear in such a context). T he preprocessor always considers a 
string constant to end at a newline 

T he preprocessor does not predefine the macro stdc when you use -traditional, but 
still predefines gnuc (sincetheGN U extensions indicated byGNuc are not affected by 
-traditional). If you need to write header files that work differently depending on 
whether -traditional is in use, by testing both of these predefined macros you can 
distinguish four situations: GNU C, traditional G N U C.otherANSI C compilers, 
and other old C compilers. 

In the preprocessor, comments convert to nothing at all, rather than to aspace This 
allows traditional token concatenation. 

String "constants" are not necessarily constant; they are stored in writable space and 
identical looking constants are allocated separately. For C++programs only (note), 
-traditional has one additional effect: assignmentto this is permitted. Thisisthe 
Same as the effect Of -f this-is-variable. 

Undefine macro macro. 

Issue warnings for conditions that pertain to usage that we recommend avoiding and 
that we believe is easy to avoid, even in conjunction with macros. 

Warn when converting between different enumeration types. 

I n a derived class, the definitions of virtual functions must match the type signature 
of a virtual function declared in the base class Use this option to request warnings 
when a derived class declares a function that may bean erroneous attempt to define 
a virtual function; that is, warn when a function with the same name as a virtual 
function in the base class, but with a type signature that doesn't match any virtual 
functionsfrom the base class 
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-wtempiate-debugging When using templates in a C++program, warn if debugging is not yet fully 

available. 

-w Inhibit all warning messages. 

+eN Control how virtual function definitionsare used, in afashion compatible with 


PRAGMAS 

Two #pragma directives are supported for GN U C++, to permit using the same header file for two purposes: as a definition of 
interfaces to a given object class, and as the full definition of the contents of that object class. 

#pragma interface Use this directive in header filesthat defineobject classes, to savespace in mostof 

theobject filesthat use those classes. Normally, local copies of certain information 
(backup copies of inline member functions, debugging information, and the internal 
tables that implement virtual functions) must be kept in each object file that 
includes class definitions. You can use this pragma to avoid such duplication. When 
a header file containing #pragma interface is included in a compilation, thisauxiliary 
information will not be generated (unless the main input source file itself uses 
#pragma implementation). Instead, the object files will contain references to be 
resolved at link time 

#pragma implementation U sethis pragma in a main input file when you want full output from included 

#pragma implementation lobjects.h! header files to be generated (and made globally visible). The included header file, in 
turn, should use#pragma interface. Backup copies of inline member functions 
debugging information, and the internal tables used to implement virtual functions 
are all generated in implementation files 

If you use ^pragma implementation with no argument, it applies to an include file 
with the same basename as your source file; for example, in aiiciass.cc, #pragma 
implementation by itself is equivalent to #pragma implementation "allclass.h". Use 
the string argument if you want a single implementation file to include code from 
multiple header files 

T here is no way to split up the contents of a si ngle header file into multiple 
implementation files. 


FILES 

file.h 

file.i 

file file.C 

file.cc 

file.cxx 

file.s 

file.o 

TMPDIR/cc 
LIBDIR/cpp 
LIBDIR/CClplus 
LIBDIR/collect 
LIBDIR/libgcc.a 
/lib/crt[01n ].0 
LIBDIR/ccrt0 
/lib/libc.a 


C header (preprocessor) file 

Preprocessed C source 

C++source file 

C++source file 

C++source file 

Assembly language file 

Object file 

Link edited output 

Temporary files 

Preprocessor 

Compiler 

Linker front end needed on some machines 
GCC subroutine library 
Start-up routine 

Additional start-up routineforC++ 
StandardC library; see intro(3) 
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/usr/inciude Standard directory for #inciude files 

LiBDiR/inciude Standard gcc directory for #inciude files 

LiBDiR/g++-inciude Additional g++directory for #inciude 

LIB DIR is usually /usr/local/lib/machinefversion. 

tmpdir comes from the environment variable tmpdir (default /usr/tmp if available else /tmp). 

SEE ALSO 

gcc(l), cpp(l), as( 1 ), ld(l), gdb(l), adb(l), dbx(l), sdb(l), gcc, cpp, as, Id, and gdb entries in info. 

Usng and Porting GNU CC (for version 2.0), Richard M . Stallman; The C Preprocessor, Richard M . Stallman; Debugging 
with GDB: theGNU Source-Level Debugger, Richard M . Stallman and Roland H. Pesch; Usngas theGNU Assembler, Dean 
Eisner, Jay Fenlason and friends; gld: theGNU linker, Steve Chamberlain and Roland Pesch. 

BUGS 

Fori nstructions on how to report bugs, see the G C C manual. 

COPYING 

Copyright © 1991,1992,1993 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim 
copies of this manual provided the copyright notice and this permission notice are preserved on all copies 
Permission isgranted to copy and distribute modified versions of this manual under the conditionsfor verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 
Permission isgranted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in theoriginal English. 

AUTHORS 

SeetheGNU CC M anual forthecontributorsto GN U CC. 

GNU Tools, 30 April 1993 

g3topbm 

g3topbm- Convert a G roup 3 fax file into a portable bitmap 

SYNOPSIS 

g3topbm [-kludge][-reversebits][-stretch][g3f i I e] 

DESCRIPTION 

Reads a Group 3 fax file as input. Producesa portable bitmap asoutput. 

OPTIONS 

-kludge Tells g3topbm to ignore the first few lines of the file; sometimesfaxfileshavesomejunk at the beginning, 

-reversebits Tells g3topbm to interpret bits least-significant first, instead Of the default most-significant first. 

Apparently, some fax modems do it one way and others do it the other way. If you get a whole bunch of 
"bad codeword" messages, try using thisflag. 

-stretch Tells g3topbm to stretch the image vertically by duplicating each row. T his isfor the low-quality transmis¬ 

sion mode. 

All flags can be abbreviated to their shortest unique prefix. 




REFERENCES 

The standard for Group 3 fax is defined in CCITT Recommendation T.4. 

BUGS 

Probably. 

SEE ALSO 

pbmtog3(l), pbm(5) 

AUTHOR 

Copyright © 1989 by Paul H aeberli (paui@manray.sgi.com) 

2 October 1989 


gawk 

gawk- Pattern scanning and processing language 

SYNOPSIS 

gawk [ POSIX or GNU style options ] -f program- f i I e [ — ] file ... 
gawk [ POSIX or GNU style options ] [ — ] program-1ext file ... 


DESCRIPTION 

gawk is the G N U Project's implementation of theawk programming language It conforms to the definition of the language 
in the 1003.2 Command Language and Utilities Standard. This version in turn isbased on the description in TheAWK 
Programming Language, by Aho, Kernighan, and Weinberger, with the additional features defined in the System V Release 4 
version of awk. gawk also providessomeGNU-specific extensions. 

The command line consists of options to gawk itself, theawk program text (if not supplied via the -f or --me options), and 
val ues to be made avai I able i n the argc and argv predefined awk vari ables 


OPTIONS 

gawk options may be either the traditional one-letter options, or the G N U -style long options T raditional style options start 
with a single -, while GNU long options start with -.GNU -style long options are provided for both GNU -specific features 
and for mandated features. 0 ther implementations of theawk language are likely to only accept the traditional one-letter 
options 


Following thestandard, gawk-specific options are supplied via argumentsto the -w option. M ultiple-w options may be 
supplied, or multiple arguments may be supplied together if they are separated by commas or enclosed in quotes and 
separated by whitespace C ase is ignored in argumentsto the-w option. Each -w option hasa corresponding G N U-style long 
option, as detailed below. Argumentsto GN U-style long options are either joined with the option by an = sign, with no 
intervening spaces or they may be provided in the next command-line argument, 
gawk accepts the following options: 


-F fs, —field-separator=fs 


Usefs for the input field separator (the value of the Fs-predefined variable). 

Assign the value va i, to the variable ■/ar, before execution of the program begins Such 
variable values are avai lable to the begin block of an awk program. 

Read theawk program source from thefilepr ogr am- f i i e, instead of from the first 
command-line argument. M ultiple-f (or -file) options may be used. 

Set various memory limits to the value nnn . T he f flag sets the maximum number of fields 
and ther flag sets the maximum record size These two flags and the-m option arefrom the 
AT&T Bell Labs research version of awk. They are ignored by gawk, since gawk has no 
predefined limits. 
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-W compat, —compat 


-W copyleft, -W copyright, 
—copyleft, —copyright 
-W help, -W usage 
—help, —usage 
-W lint, —lint 

-W posix, —posix 


-W source=program-text, 


—source=pr ogr am-1 ext 



Run in compatibility mode In compatibility mode gawk behave identically to awk; none of 
theG N U -specific extensionsare recognized. See "G N U Extensions," later in this manual 
page, for more information. 

Print the short version of theGN U copyright information message on the error output. 

Print a relatively short summary of the available options on the error output. Per the G N U 
Coding Standards, these options cause an immediate successful exit. 

Provide warnings about constructs that are dubious or nonportable to other awk implemen¬ 
tations. 

This turns on compatibility mode, with the following additional restrictions\x escape 
sequences are not recognized. 

The synonym tunc for the keyword function is not recognized. 

The operators** and **= cannot be used in place of ‘ and ■=. 

Useprogram-text asawk program source code Thisoption allowstheeasy intermixing of 
library functions (used via the-t and -me options) with source code entered on the 
command line. It is intended primarily for medium to large awk programs used in shell 
scripts. 

The-w source^ form of this option uses the rest of the command-line argument for 
program-text ; no other options to -wwill be recognized in the same argument. 

Print version information for this particular copy of gawk on the error output. This is useful 
mainly for knowing if the current copy of gawk on your system is up-to-date with respect to 
whatever the Free Software Foundation is distributing. PertheGNU Coding Standards, 
these options cause an immediate, successful exit. 

Signal the end of options. This is useful to allow further arguments to the awk program itself 
to start with a-.This is mainly for consistency with the argument-parsing convention used 
by most other programs. 


In compatibility mode any other options are flagged as illegal, but are otherwise ignored. In normal operation, as long as 
program text has been supplied, unknown options are passed on to the awk program in theARGv array for processing. This is 
particularly useful for running awk programs via the#! executable interpreter mechanism. 


awk PRO GRAM EXECUTION 

An awk program consists of a sequence of pattern-action statements and optional function definitions 

pattern { action statements } 

function name (parameter list) { statements } 

gawk first reads the program source from the program-f i le{s) if specified, from arguments to -w sources or from thefirst 
nonoption argument on the command line. The-f and -w source= options may be used multi pie times on the command 
line gawk will read the program text as if all the program-files and command-line sourcetexts had been concatenated 
together. This is useful for building libraries of awk functions without having to include them in each new awk program that 
uses them. It also provides the ability to mix library functions with command-line programs 

T he environment variable awkpath specifies a search path to use when finding source files named with the-f option. If this 
variable does not exist, the default path is.: /usr/iib/awk: /usr/iocai/iib/awk. 

If a filename given to the -f option contains a / character, no path search is performed. 

gawk executes awk programs in the following order. First, all variable assignments specified via the -v option are performed. 
Next, gawk compiles the program into an internal form. Then, gawk executes the code in the begin block(s) (if any), and then 
proceeds to read each file named in theARGv array. If there are no files named on thecommand line, gawk reads the standard 
input. 

If a filename on thecommand line has the form var=*ai , it istreated as a variable assignment. The variable var will be 
assigned the value vai . (This happens after any begin block(s) have been run.) Command-line variable assignment ismost 
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useful for dynamically assigning values to the variables awk uses to control how input is broken into fields and records It is 
also useful for controlling state if multiple passes are needed over a single data file 
If the value of a particular element of argv isempty (■ ■), gawk skips over it. 

For each line in the input, gawk tests to see if it matches any pattern in the awk program. For each pattern that the line 
matches, the associated action is executed. The patterns are tested in the order they occur in the program. 

Finally, after all the input is exhausted, gawk executes the code in the end block(s) (if any). 

VARIABLES AND FIELDS 

awk variables are dynamic; they come into existence when they are first used. T heir values are either floating-point numbers 
or strings, or both, depending upon how they are used, awk also has one-dimensional arrays; arrays with multiple dimensions 
may be simulated. Several predefined variables are set as a program runs; these will be described as needed and summarized 
in the "Built-In Variables" subsection. 

FIELDS 

As each input line is read, gawk splits the line into fields, using the value of the fs variable as the field separator. If fs is a 
single character, fields are separated by that character. Otherwise, fs is expected to be a full regular expression. In the special 
case that fs is a single blank, fields are separated by runs of blanks or tabs. N ote that the value of ignorecase (seethe 
following) will also affect how fields are split when fs is a regular expression. 

If the fieldwidths variable isset to a space separated list of numbers, each field isexpected to have fixed width, and gawk will 
split up the record using the specified widths. The value of fs is ignored. Assigning a new value to fs overrides the use of 
fieldwidths, and restores the default behavior. 

Each field in the input line may dereferenced by its position, $1, $2, and so on. $0 isthewhole line The value of afield may 
be assigned to as well. Fields need not be referenced by constants 



prints the fifth field in the input line The variable nf isset to the total number of fields in the input line 
References to nonexistent fields (that is, fields after $nf) produce the null-string. Flowever, assigning to a nonexistent field 
(for example, $<nf+ 2 ) = 5 ) will increase the value of nf, create any intervening fieldswith the null string astheir value, and 
cause the value of $0 to be recomputed, with the fields being separated by the value of ofs. References to negative-numbered 
fields cause a fatal error. 

BUILT-IN VARIABLES 

awk's built-in variables are the following: 

argc T he number of command-line arguments (does not include options to gawk, or the program source). 

argind T he index in argv of the current file being processed. 

argv Array of command-line arguments The array is indexed from 0 to argc - 1 . Dynamically changing the 

contents of argv can control thefilesused for data. 
convfmt The conversion format for numbers, "%.6g”, by default. 

environ An array containing the values of the current environment. The array isindexed by the environment 

variables, each element being the value of that variable (for example, environ ["home 11 ] might be/u/arnoid). 
C hanging this array does not affect the environment seen by programs which gawk spawns via redirection 
or the system 0 function. (Thismay change in afuture version of gawk.) 
errno If a system error occurs either doing a redirection for getiine, during a read for getiine, or during a 

cioseo, then errno will contain a string describing the error. 
fieldwidths A whitespace-separated list of fieldwidths. W hen set, gawk parses the input into fields of fixed width, 
instead of using the value of the fs variable as the field separator. The fixed field width facility isstill 
experimental; expect the semantics to change asgawk evolves over time. 
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filename T he name of the current input file If no files are specified on the command line, the value of filename is-. 

However, filename is undefined inside the begin block. 
fnr The input record number in the current input file. 

fs The input field separator, a blank by default. 

ignorecase Controls thecase-sensitivity of all regular expression operations If ignorecase has a nonzero value, then 

pattern matching in rules field splitting with fs, regular expression matching with - and r, and the 
gsubf), indexf), match(), spiit( ),and sub( ) predefined functionswill all ignore case when doing regular 
expression operations. Thus if ignorecase is not equal to zero, /aB/ matches all of the strings ab, aB, Ab, 
and ab. As with all awk variables the initial value of ignorecase is zero, so all regular expression operations 
are normally case-sensitive. 

nf The number of fields in thecurrent input record. 

nr The total number of input records seen so far. 

ofmt The output format for numbers, "%.6g", by default. 

ofs The output field separator, a blank by default. 

ors Theoutput record separator, by default a newline. 

rs The input record separator, by default a newline, rs is exceptional in that only the first character of its 

string value is used for separating records. (T his will probably change in a future release of gawk.) If rs is set 
to the null string, then records are separated by blank lines. When rs isset to the null string, then the 
newlinecharacter always actsasa field separator, in addition to whatever value fs may have. 
rstart The index of thefirst character matched by match(); 0 if no match. 

rlength Thelength of the string matched by match(); -1 if no match. 

subsep The character used to separate multiple subscripts in array elements, by default n034. 

ARRAYS 

Arrays are subscripted with an expression between square brackets. If the expression isan expression list (expr, expr ...) 
then the array subscript is a string consisting of the concatenation of the (string) value of each expression, separated by the 
value of the subsep variable. This facility is used to simulate multiply dimensioned arrays For example, 

i = "A" ; j = "B" ; k = "C" 
x[i, j, k] = "hello, world\n" 

assigns the string hello, worid\ntotheelementofthearrayxwhich isindexed by thestring "a\034b\034C". All arraysin awk 
are associative, that is indexed by string values. 

The special operator in may be used in an it or while statement to see if an array has an index consisting of a particular 
value: 

if (val in array) 
print array[val] 

If the array has multiple subscripts useu.mn array. 

T he in construct may also be used i n a f or loop to iterate over all the elements of an array. 

An element may be deleted from an array using the delete statement. T he delete statement may also be used to delete the 
entire contents of an array. 

VARIABLETYPING AND CONVERSION 

Variables and fields may be floating-point numbers, or strings or both. H ow the value of a variable is interpreted depends 
upon its context. If used in a numeric expression, it will be treated asanumber; if used asastring, it will be treated asa 
string. 

To force a variable to be treated asanumber, add 0 to it; to force it to be treated asastring, concatenate it with the null 
string. 
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When a string must be converted to a number, the conversion is accomplished using atof( 3 ). A number isconverted to a 
string by using the value of convfmt as a format string for sprintf ( 3 ), with the numeric value of the variable as the argument. 
However, even though all numbers in awk are floating-point, integral values arealways converted as integers. Thus, given this: 

CONVFMT = "%2.2f" 
a =12 


the variable b has a string value of 12 and not 12.00. 

gawk performs comparisons as follows: If two variables are numeric, they are compared numerically. If one value is numeric 
and the other has a string value that is a "numeric string," then comparisons are also done numerically. Otherwise, the 
numeric value isconverted to a string and a string comparison is performed. Two strings are compared, of course, as strings. 
According to the standard, even if two strings are numeric strings, a numeric comparison is performed. H owever, this is 
clearly incorrect, and gawk does not do this 

Uninitialized variables have the numeric value 0 and the string value ■■ (the null, or empty, string). 

PATTERN SAND ACTIONS 

awk is a line-oriented language. The pattern comes first, and then the action. Action statements are enclosed in and .br. 

Either the pattern may be missing, or the action may be missing, but, of course, not both. If the pattern is missing, the action 
will be executed for every single lineof input. A missing action is equivalent to 

{ print } 

which prints theentire line 

Comments begin with the# character, and continue until the end of the line. Blank lines may be used to separate state¬ 
ments Normally, a statement ends with a newline however, this is not the case for linesending in a,, {, ?, or \ Lines 
ending in do or else also have their statements automatically continued on thefollowing line In other cases, a line can be 
continued by ending it with a \, in which case the newline will be ignored. 

M ultiple statements may be put on onelineby separating them with a semicolon. Thisappliesto both the statements within 
the action part of a pattern-action pair (the usual case), and to the pattern-action statements themselves 

PATTERNS 

awk patterns may be one of the following: 

BEGIN 

END 

relational expression 
pattern && pattern 
pattern jj pattern 
pattern ? pattern : pattern 
(pattern) 


begin and end are two special kinds of patterns that are not tested against the input. The action parts of all begin patterns are 
merged as if all the statements had been written in a single begin block. They are executed before any of the input is read. 
Similarly, all the end blocks are merged, and executed when all the input is exhausted (or when an exit statement is 
executed), begin and end patterns cannot be combined with other patterns in pattern expressions begin and end patterns 
cannot have missing action parts 

For /regui ar expressi on / patterns, the associated statement isexecuted for each input line that matches the regular 
expression. Regular expressions are the same as those in egrep(l), and are summarized as follows: 
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A rei at i onai expressi on may use any of the operators defined later in the section on actions. These generally test whether 
certain fields match certain regular expressions 

The&&, 11, and i operators are logical and, logical or, and logical not, respectively, as in C. They do short-circuit evaluation, 
also as in C, and are used for combining more primitive pattern expressions As in most languages, parentheses may be used 
to change the order of evaluation. 

The?: operator islike the same operator in C. If thefirst pattern istrue, then the pattern used fortesting isthe second 
pattern; otherwise, it is the third. Only one of the second and third patterns is evaluated. 

The pat t er ni, pattern? form of an expression iscalled a range pattern. It matches all input recordsstarting with a line that 
matchespa 11 er n 1 , and continuing until a record that matchespat ter n2, inclusive It does not combine with any other sort of 
pattern expression. 

REGULAR EXPRESSIONS 

Regular expressions are the extended kind found in egrep. They are composed of characters as follows: 
c M atches the non-meta-character c. 

\c M atches the literal character c. 

M atches any character except newline 
M atchesthe beginning of a lineor a String. 

$ Matches the end of a line or a string. 

[a be... ] C haracter class, matches any of the characters abc.... 

[ “a b c... ] Negated character class, matchesany character except abc... and newline 
r 1 ;r 2 Alternation: matches either ri or r 2. 

rlr2 Concatenation: matchesn, and then r 2. 

r + M atches one or more rs 

r * M atches zero or more r s 

r? Matches zero or oners. 

(r) Grouping: matches r. 

The escape sequences that are valid in string constants are also legal in regular expressions 

ACTIONS 

Action statements are enclosed in braces { and >. Action statements consist of the usual assignment, conditional, and looping 
statements found in most languages. The operators control statements and input/output statements available are patterned 
after those in C. 

OPERATORS 

The operators in awk, in order of increasing precedence are 

=+=-= Assignment. Both absolute assignment (* a r = »ai ue) and operator-assignment (the other forms) are 

*= /= %= ■= supported. 

?: TheC conditional expression. Thishastheformexpri ? expr 2 : expr 3 .Ifexpri istrue, the value of the 

expression isexpr 2; otherwise it isex pr 3 . Only one of expr 2 and expr 3 is evaluated. 

11 Logical or. 

&& Logical and. 

t Regular expression match, negated match. NOTE: Do not use a constant regular expression (/too/) to the 

left of a ' or r. Only useoneon therightside. Theexpression /too/ ' exp hasthesame meaning as (($0 
• /too/) ' exp). T hisis usually not what was intended. 

< >, <=>= The regular relational operators, 

blank String concatenation. 

+- Addition and subtraction. 






*/% M ultiplication, division, and modulus. 

+-! Unary plus unary minus, and logical negation. 

Exponentiation (** may also be used, and **= for the assignment operator). 
++ — Increment and decrement, both prefix and postfix. 

$ Field reference 

CONTROL STATEMENTS 

The control statements are as follows: 

if (condition) statement [ else statement ] 
while (condition) statement 
do statement while (condition) 
for (exprl; expr2; expr3) statement 
for (var in array) statementbreak 


delete array[index] 
delete array 

{ statements } 


I/O STATEMENTS 

The input/output statements are as follows: 


close(f i I ename) 




printf f mt, e x p r -1 i s t >f i I e 
system(cmd- line) 


Closefile (or pipe, see paragraph following thislist). 

Set $0 from next input record; set nf, nr, fnr. 

Set $0 from next record of f i i e ; set nf. 

Set var from next input record; set nf, fnr. 

Set var from next record of f i i e. 

Stop processing the current input record. The next input record isread and processing starts 
over with the first pattern in the awk program. If the end of the input data is reached, the 
end block(s), if any, are executed. 

Stop processing the current input file. The next input record read comes from the next 
input file filename is updated, fnr is reset to i, and processing starts over with thefirst 
pattern in the awk program. If the end of the input data is reached, the end block(s), if any, 
are executed. 

Prints the current record. 

Prints expressions. Each expression isseparated by the value of the ofs variable. The output 
record is terminated with the value of the ors variable 

Prints expressions on f i i e. Each expression isseparated by the value of the ofs variable The 
output record is terminated with the value oftheoRs variable 
Format and print. 

Format and print on f i i e. 

Executethecornrnandcmd-i i ne, and return the exit status. (This may not be available on - 
PO SIX systems.) 


Other input/output redirections are also allowed. For print and printf, »nie appends output to then i e, while | command 
writes on a pipe. In a similar fashion, command | getiine pipes into getiine.Thegetiine command will return 0 on end of 
file, and -1 on an error. 


THE printf STATEMENT 

The awk versions of the printf statement and sprintff) function accept the following conversion specification formats: 

%c An ASCI I character. If the argument used for %c is numeric, it is treated as a character and printed. 

Otherwise, the argument is assumed to be a string, and the only first character of that string is printed. 
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%d A decimal number (the integer part). 

%i Just like%d. 

%e A floating-point number of theform [-]d.ddddddE[+-]dd. 

%f A floating-point number of theform [-iddd.dddddd. 

%g Useeort conversion, whichever is shorter, with nonsignificant zeros suppressed. 

%o An unsigned octal number (again, an integer). 

%s A character string. 

%x An unsigned hexadecimal number (an integer). 

%x Like%x,butusingABCDEF instead of abcdef. 

%% A single % character; no argument isconverted. 

T here are optional, additional parameters that may lie between the % and the control letter: 

Theexpression should be left-justified within itsfield. 

sglifi Thefield should be padded to this width. If the number has a leading zero, then thefield will be padded 

with zeros. 0 therwise, it is padded with blanks This applies even to the nonnumeric output formats. 

.prec A number indicating the maxi mum width of strings or digits to the right of the decimal point. 

The dynamic wi dth and prec capabilities of the C printfO routines are supported. A * in place of either the wi dt h or prec 
specifications will cause their values to betaken from the argument list to printf or sprinttf). 

SPECIAL FILENAMES 

When doing I/O redirection from either print or printf into a file, or viagetiine from a file, gawk recognizes certain special 
filenames internally. These filenames allow access to open file descriptors inherited from gawk's parent process (usually the 
shell). Other special filename provide access information about the running gawk process. The filename are 
/dev/pid Reading thisfile returns the process ID of the current process, in decimal, terminated with a newline, 

/dev/ppid Reading thisfile returns the parent process ID of the current process, in decimal, terminated with a 

newline 

/dev/pgrpid Reading thisfile returns the process group ID ofthecurrent process, in decimal, terminated with a 
newline 

/dev/user Reading thisfile returns a single record terminated with a newline. Thefields are separated with blanks $1 
isthe value of the getuid(2) system call, $2 isthe value of thegeteuid(2) system call, $3 is the value of the 
getgid(2) system call, and $4 is the value of thegetegidf 2) system call. I f there are any additional fields, 
they are the group IDs returned by getgroups( 2 ). M ultiple groups may not be supported on all systems, 
/dev/stdin Thestandard input. 

/dev/stdout Thestandard output. 

/dev/stderr Thestandard error output. 

/dev/fd/n The file associated with theopen file descriptor n. 

These are particularly useful for error messages For example, you could use 

print "You blew it!" > "/dev/stderr" 

whereas you would otherwise have to use 

print "You blew it!" ] "cat 1>&2" 

These filenames may also be used on the command lineto name data files 

NUMERIC FUNCTIONS 

awk has thefollowing predefined arithmetic functions: 
atan 2 (y, x) Returns the arctangent ofy/x in radians, 
cos (e x p r ) Returns the cosine in radians 
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exp(expr) The exponential function. 

int(expr) Truncates to integer. 

log(expr ) The natural logarithm function. 

rand() Returns a random number between 0 and 1. 

sin(expr) Returnsthesinein radians. 

sqrt(expr) The square root function. 

srand(expr) Useexpr as a new seed for the random number generator. If no expr is provided, the time of day will be 
used. The return value is the previous seed for the random number generator. 


STRING FUNCTIONS 


awk has the following predefined string functions 


gsub(r , s, t) 

index(s , t ) 
length (s) 
match(s , r ) 

split (s , a, r) 

sprintf(fmt , expr■Iist ) 

substr(s, i , n) 
tolower(st r) 

toupper(st r) 


For each substring matching the regular expression r in the string t, substitute the strings, 
and return the number of substitutions. If t isnot supplied, use $0. 

Returnsthe index of the string t in the strings,or 0 if t isnot present. 

Returnsthe length of the strings, or the length of $0 if s isnot supplied. 

Returnsthe position in s where the regular expression r occurs, or 0 if u is not present, and 
sets the values of rstart and rlength. 

Splitsthe strings into the array a on the regular expression r, and returnsthe number of 
fields. If r isomitted, Fsisused instead. The array a is cleared first. 

P ri nts expr-1 i st according to fmt , and returns the resulting string. 

J ust like gsubQ, but only thefirst matching substring is replaced. 

Returns then-character substring of s starting at i. If n is omitted, the rest of s isused. 
Returns a copy of the string s t r , with all the uppercase characters in s t r translated to their 
corresponding lowercase counterparts. N onalphabetic characters are left unchanged. 
Returns a copy of the string str, with all the lowercase characters in st r translated to their 
corresponding uppercase counterparts N onalphabetic characters are I eft unchanged. 


TIME FUNCTIONS 

Since one of the primary uses of awk programs is processing log files that contain time stamp information, gawk provides the 

following two functionsfor obtaining time stamps and formatting them. 

systimeo Returns the current time of day as the number of secondssincethe Epoch (M idnight UTC, 

J anuary 1,1970 on systems). 

strftime(f or mat , ti mestamp) FormatSt i mest amp according to the Specification informat. Theti mestamp should beofthe 
sameform as returned by systimeo. If ti mestamp is missing,the current timeof day isused. 
See the specification forthestrftimeo function in C fortheformat con versions that are 
guaranteed to be available A public-domain version of strftime( 3 ) and a man page for it are 
shipped with gawk; if that version was used to build gawk, then all of the conversions 
described in that man page are availableto gawk. 


STRING CONSTANTS 

String constants in awk are sequences of characters enclosed between double quotes (■). Within strings, certain escape 
sequences are recognized, as i n C. T hese are 
u A literal backslash. 

\a The "alert" character; usually the ASC11 BEL character. 

\b Backspace. 

\t Formfeed. 

\n Newline. 
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\r Carriage return. 

\t H orizontal tab. 

\v Vertical tab. 

\xhex digits The character represented by the string of hexadecimal digits following the\x. As in C, all following 

hexadecimal digits are considered part of the escape sequence. (Thisfeature should tell us something about 
language design by committee.) For example, "\xib" isthe ASC11 ESC (escape) character. 

\ ddd The character represented bythel-, 2-, or 3-digit sequence of octal digits For example, "\ 033 " isthe 

ASCII ESC (escape) character, 

c The literal character c. 

The escape sequences may also be used inside constant regular expressions (for example, / [\\t\f\n\r\v] / matches whitespace 
characters). 

FUNCTIONS 

Functions in awk are defined asfollows 

function name (parameter list) { statements } 

Functions are executed when called from within the action parts of regular pattern-action statements Actual parameters 
supplied in thefunction call are used to instantiate the formal parameters declared in thefunction. A mays are passed by 
reference, other variables are passed by value. 

Functions were not originally part of the awk language, so the provision for local variables is rather clumsy: They are declared 
as extra parameters in the parameter list. The convention is to separate local variablesfrom real parameters by extra spaces in 
the parameter list. For example 



The left parenthesis in afunction call isrequired to immediately follow thefunction name without any intervening 
whitespace. This is to avoid a syntactic ambiguity with the concatenation operator. This restriction does not apply to the 
built-in functions listed earlier. 

Functions may call each other and may be recursive. Function parameters used as local variables are initialized to the null 
string and the number zero upon function invocation. 

The word tunc may be used in place of function. 

EXAMPLES 

Print and sort the login names of all users 



Precede each line by its number in thefile: 

{ print FNR, $0 } 

Concatenate and linenumber (a variation on atheme): 
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SEE ALSO 

egrep(l), getpid(2), getppid(2), getpgrp(2), getuid(2), geteuid(2), getgid(2), getegid(2), get-groups(2) 

TheAWK Programming Language, Alfred V. Aho, Brian W. Kernighan, Peter J. Weinberger, Addison-W esley, 1988. ISBN 
0-201-07981-X. 

TheGAWK Manual, Edition 0.15, published by the Free Software Foundation, 1993. 

P0SIX COMPATIBILITY 

A primary goal for gawk is compatibility with the standard, as well as with the latest version of awk. To this end, gawk 
incorporates the following user-visible features that are not described in the awk book, but are part of awk in SystemV 
Release 4, and are in the standard. 

The-v option for assigning variables before program execution starts is new. The book indicates that command-line variable 
assignment happens when awk would otherwise open the argument as a file which is after the begin block is executed. 
However, in earlier implementations, when such an assignment appeared before any filenames, the assignment would happen 
before the begin block was run. Applications came to depend on this "feature." When awk was changed to match its 
documentation, this option was added to accommodate applications that depended upon the old behavior. (This feature was 
agreed on by both the AT & T and G N U developers.) 

The -w option for implementation-specific features isfrom the standard. 

When processing arguments, gawk uses the special option - to signal the end of arguments. In compatibility mode it will 
warn about, but otherwise ignore undefined options In normal operation, such arguments are passed on to the awk program 
for it to process. 

The awk book does not define the return value of srando. The System V Release 4 version of awk (and the standard) has it 
return the seed it was using, to allow keeping track of random number sequences. Therefore srand() in gawk also returns its 
current seed. 

0 ther new features are: the use of multiple -f options (from M K S awk); the environ array; the \a, and \v escape sequences 
(done originally in gawk and fed back into AT & T's version); the toiowerf) and toupper() built-in functions (from AT& T); 
and theC conversion specifications in printf (done first in AT&T's version). 

GNU EXTENSIONS 

gawk has some extensions to awk. They are described in thissection. All the extensions described here can be disabled by 
invoking gawk with the -w compat option. 

Thefollowing features of gawk are not available in awk: 

The \x escape sequence. 

Thesystimeo and strftimeo functions 

The special filenames available for I/O redirection are not recognized. 

The argind and errno variables are not special. 

TheiGNORECASE variable and its side effects. 

TheFiELDwiDTHs variable and fixed width field splitting. 

N o path search is performed for files named via the -f option. T herefore, the awkpath environment variable is not special. 
The use of next file to abandon processing of the current input file. 

The use of delete array to delete the entire contentsof an array. 

The awk book does not definethe return value of the close o function, gawk'scioseo returns the value from fciose(3),or 
pciose(3), when closing a file or pipe, respectively. 

When gawk is invoked with the -w compat option, if the fs argument to the -f option is t, then fs will be set to thetab 
character. Since thisisa rather ugly special case it is not thedefault behavior. T his behavior also does not occur if -wposix 
has been specified. 
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HISTORICAL FEATURES 

There are two features of historical awk implementations that gawk supports First, it is possible to call theiengtho built-in 
function not only with no argument, but even without parentheses! Thus, this 

a = length 

is the same as ei ther of these: 

a = length() 
a = length($0) 

This feature is marked as "deprecated" in the standard, and gawk will issue a warning about its use if -w unt isspecified on 
thecommand line 

T he other feature is the use of either the continue or the break statements outside the body of a while, tor, or do loop. 

T raditional awk implementations have treated such usage as equivalent to the next statement, gawk will support this usage 
if-w compat has been specified. 

EN VIRO N M EN T VARIABLES 

If posixly_correct exists in the environment, then gawk behaves exactly as if - -posix had been specified on thecommand 
line If --lint has been specified, gawk will issue a warning message to this effect. 

BUGS 

T he -f option is not necessary given thecommand-line variable assignment feature; it remains only for backwards compat¬ 
ibility. 

If your system actually has support for /dev/td and the associated /dev/stdin, /dev/stdout, and /dev/stderr files, you may get 
different output from gawk than you would get on a system without those files. When gawk interprets these files internally, it 
synchronizesoutput to the standard output with output to /dev/stdout, while on a system with those files, the output is 
actually to different open files C aveat emptor. 

VERSION INFORMATION 

This man page documents gawk, version 2.15. 

Starting with the 2.15 version of gawk, the-c, -v, -c, -d, -a, and -e options of the 2.11 version are no longer recognized. This 
fact will not even be documented in the manual page for the next major version. 

AUTHORS 

The original version of awk was designed and implemented by Alfred Aho, Peter Weinberger, and Brian Kernighan of AT&T 
Bell Labs Brian Kernighan continues to maintain and enhance it. 

Paul Rubin and Jay Fenlason, of the Free Software Foundation, wrote gawk, to be compatible with the original version of awk 
distributed in theseventh edition. John Woods contributed a number of bugfixes David Trueman, with contributionsfrom 
Arnold Robbins made gawk compatible with the new version of awk. Arnold Robbins is the current maintainer. 

The initial DO Sport was done by Conrad Kwok and Scott Garf inkle. Scott Deifik is the current DOS maintainer. Pat 
Rankin did the port to V M S, and M ichal J aegermann did the port to the Atari ST. T he port to 0 S/2 was done by Kai U we 
Rommel, with contributions and help from D arrel H ankerson. 

BUG REPORTS 

If you find a bug in gawk, please send electronic mail to 
bug-gnu -utils@prep.ai.mit.edu, 

with acopyto amoid@gnu.ai.mit.edu. Please include your operating system and its revision, the version of gawk.whatC 
compiler you used to compile it, and a test program and data that are as small as possiblefor reproducing the problem. 
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Beforesending a bug report, pleasedotwo things First, verify that you have the latest version of gawk. M any bugs (usually 
subtle ones) are fixed at each release, and if yours is out of date, the problem may already have been solved. Second, please 
read this man page and the reference manual carefully to be sure that what you think is a bug really is instead of just a quirk 
in the language. 

ACKNOWLEDGMENTS 
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Wethank him. 

F ree SoftwareF oundation, 24 N member 1994 


gcal 

gcai— Displays month/year calendar sheets eternal holiday lists for Julian and Gregorian years, and fixed date warning 
lists— all in a variety of ways. 

SYNOPSIS 

gcal [[ Option... ][%Date ][@File... ]] [ Command ] 

DESCRIPTION 

gcai isaprogram similar the standard calendar programs BSD-'cai 1 and calendar, 
gcai displaysG regorian calendars, J ulian calendars (before September 1752). 

If gcai is started without any options or commands a calendar of the current month is displayed. 

If the calendar of a definite year is wanted, the year must be fully specified. For example, gcai 94 displays a year calendar of 
the year 94, not of the year 1994. 

If two arguments are given in the command part, the first argument denotes the month and the second argument denotes the 
year. In case any illegal commandsaregiven running gcai, the program will use internal defaults 
The Gregorian Reformation isassumed to have occurred in 1752 on the 3rd of September. Ten days following that date 
were eliminated by the reformation, so the calendar for that month is a bit unusual. 

MO RE PRO GRAM INFORMATION 

You get more program information if you start gcai as follows: 
gcal -h gcal -? gcal -help 

gcal -hh gcal ■?? gcal -long-help[=ARG]j[=?] gcal -usage[=ARG]j[=?] 

A hypertext file gcai.info containing detailed online information should be available which you can inspect using your 
GNU Infobrowser. 

COPYRIGHT 

gcai copyright© 1994,1995,1996 by Thomas Esken. This software doesn't claim completeness, correctness, or usability. 
On principle I will not be liablefor any damages or losses (implicit or explicit), which result from using or handling my 
software. If you use this software, you agree without any exception to this agreement, which binds you legally, 
gcai isfree software and distributed under the terms of theGN U General Public License; published by the Free Software 
Foundation; version 2 or (at your option) any later version. 

Any suggestions, improvements, extensions, bug reports, donations, proposals for contract work, and so forth are welcome! 
If you likethistool, I'd appreciate a postcard from you! 

Enjoy it =8") 
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AUTHOR 

ThomasEsken (esken@uni-muenster.de) 
lm H agenfeld 84 
D-48147 M uenster; Germany 
Phone:+49 251 232585 

SEE ALSO 

cal(l), calendar(l) 

16 July 1996 
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gcc,g++— GNU projectC andC++Compiler(v2.7) 

SYNOPSIS 

gcc [option j f i I ename ]. . . 

WARNING 

The information in this man pageisan extract from the full documentation of theGN U C compiler and islimitedtothe 
meaning of the options 

This man page is not kept up-to-date except when volunteers want to maintain it. If you find a discrepancy between the man 
page and thesoftware, please check the into file which istheauthoritativedocumentation. 

If we find that thethings in this man page that are out of date cause significant confusion or complaints, we wi II stop 
distributing the man page The alternative updating the man page when we update the into file, is impossible because the 
restoftheworkofmaintainingGNU CC leavesus no timefor that. TheGN U project regards man pages as obsolete and 
should not let them take time away from other things. 

For complete and current documentation, refer to the info file gcc or the manual U sing and Porting GNU CC (for version 
2.0). Both aremadefrom the Texinfo source file gcc. texinfo. 

DESCRIPTION 

TheC and C++compilers are integrated. Both process input files through one or more of four stages: preprocessing, 
compilation, assembly, and linking. Source filename suffixes identify the source language, but which name you use for the 
compiler governs default assumptions 

gcc Assumes preprocessed (.i) files are C and assumes C-style linking. 

g++ Assumes preprocessed (.i) files are C++and assumesC++~style linking. 

Suffixes of source filenames indicate the language and kind of processing to be done: 

.c C source; preprocess compile, assemble 

.c C ++source preprocess, compile, assemble 

.cc C ++source preprocess, compile, assemble 

.cxx C ++source preprocess, compile, assemble 

.m 0 bjective-C source; preprocess compile assemble 

.i Preprocessed C; compile, assemble 

.11 Preprocessed C++; compile assemble 

.s Assembler source; assemble 
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.s Assembler source; preprocess, assemble 

.h Preprocessor file; not usually named on command line 

Files with other suffixes are passed to the linker. Common casesinclude 

.0 Object file 
.a Archive file 

Linking isalways the last stage unless you use one of the-c, -s, or -e options to avoid it (or unless compilation errorsstop 
the whole process). For the link stage, all . o files corresponding to sourcefiles, -1 libraries, unrecognized filenames (including 
named .0 object files, and .a archives) are passed to the linker in command-line order. 


OPTIONS 


Options must be separate -dr is quite different from -d -r. 

Most-f and -w options have two contrary forms:-f name and -fno-name (or-wname and -wno-n a me). Only the nondefault forms 
are shown here 

FI ere isa summary of all the options, grouped by type. Explanations are in thefollowing sections. 

Overall Options 

-c -S -E -0 fiIe -pipe -v -x Ianguage 

Language Options 


-fdollars-in-identifiers 

-fsigned-bitfields 
-funsigned-bitfields 
-traditional 


-fall-virtual 
-fenum-int-equiv 
-fno-builtin 
-fsigned-char 
-funsigned-char 
-traditional-cpp 


-fcond-mismatch 
-fexternal-templates 
-fno-strict-prototype 
-fthis-is-variable 
-fwritable-strings 
-trigraphs 


Warning Options 

-fsyntax-only 

-w -W -Wall 

-Wcast-qual 

-Wconversion 

-Wformat 

-Winline 

-Wnested-externs 

-Wpointer-arith 

-Wshadow 

-Wtemplate-debugging 


-pedantic 

-Waggregate-return 

-Wchar-subscript 

-Wenum-clash 

-Wid-clash-len 

-Wmissing-prototypes 

-Wredundant-decls 

-Wstrict-prototypes 

-Wtraditional 

-Wunused 


-pedantic-errors 

-Wcast-align 

-Wcomment 

-Wmissing-declarations 

-Wparentheses 

-Wreturn-type 

-Wtrigraphs 

-Wwrite-strings 


Debugging Options 

-a -dletters -fpretend-float -g -gleveI -gcoff -gxcoff -gxcoff+ -gdwarf -gdwarf+ -gstabs -gstabs+ 
save- temps -print-file-name=l i brary -print-libgcc-file-name - print-prog-name=program 


Optimization Options 

-fcaller-saves 
-fdelayed-branch 


-fforce-mem 


-fcse-follow-j umps 
-felide-construotors 
-ffloat-store 
-finline-functions 


-fcse-skip-blocks 
-fexpensive-optimizations 
-fforce-addr 
-fkeep-inline-functions 


-pg - 





Parti: User Commands 


176 


-fmemorize-lookups 
-fno-function-cse 
-fomit-frame-pointer 
-fschedule-insns2 
-funroll-all-loops 


-fno-default-inline 

-frerun-cse-after-loop 
-fstrength-reduce 
-funroll-loops 


-fno-defer-pop 
-fno-peephole 
-fschedule-insns 
-fthread-jumps 
-0 -02 


-Aassertion -C -dD -dM -dN -Dmacr o[=defn ]-E -H- idirafter dir -include f i I e -imacrosfile -iprefix f i I e - 
iwithprefix dir -M -MD -MM -MMD -nostdinc -P -Umacro -undef 

Assembler Option 

-Wa.option 

Linker Options 

-llibrary -nostartf iles -nostdlib -static -shared -symbolic -Xlinkernopt i on -Wl,opt i o n -u symbol 

Directory Options 

-Bprefix -Idir -I- -Ldir 

T arget 0 ptions 

-b machine -V version 

C onfiguration-D ependent 0 ptions 

M 680x0 Options 

-m68000-m68020 -m68020-40-m68030-m68040-m68881 -mbitfield -mc68000 -mc68020 -mfpa -mnobitfield -mrtd -mshort -msoft- 
float 


VAX Options 

-mg -mgnu -munix 

SPARC Options 


-mepilogue -mfpu -mhard-float -mno-fpu 


-mno-epilogue -msoft-float -msparclite -mv8 -msupersparc -mcypress 


ConvexOptions 

-margcount -mcl -mc2 -mnoargcount 


AM D29K Options 

-m29000-m29050 -mbw -mdw 

M 88K Options 

-m88000 -m88100 -m88110 
-mcheck-zero-division 
-midentity-revision 
-mno-ocs-debug-info 

-mno-underscores 

-mserialize-volatile 

-muse-div-instruction 


-mkernel-registers -mlarge -mnbw -mnodw -msmall -mstack-check 


-mhandle-large-shift 


-mno-ocs-frame-position 
-mno-serialize-volatile 


-moptimize-arg-area 

-mshort-data-num 

-mtrap-large-shift 

-mversion-03.00 


-muser-registers 


i-passed-structs 
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RS6000 Options 

-mfp-in-toc -mno-fop-in-toc 

RT Options 

-mcall-lib-mul -mfp-arg-in-fpregs 

-mfull-fp-blocks -mhc-struct-return 

-mmimmum-fp-blocks 

Ml PS Options 

-mcpu=cpu type -mips2 -mips3 

-mlonglong128 

-mno-rnames 

-mno-stats -mmemcpy -mno-memcpy -mno-mips-tfile 
-mmips-tfile 

-mno-abicalls -mhalf-pic -mno-half-pic -G num -nocpp 

i386 Options 

-m486 -mno-486-msoft-float-mno-fp-rdt-in-387 
HPPA Options 

-mpa-rise-1-0 -mpa-rise-1-1 -mkernel -mshared-libs- 
indexing -mtrailing- colon 

i960 Options 

-mepu-type 
-mnumerics 

-mno-leaf-procedures 
-mcomplex-addr 
-mno-code-align 
-mic3.0-compat 
-mstrict-align 
-mno-old-align 

DEC Alpha Options 

-mfp-regs -mno-fp-regs -it 

System V Options 


-mno-complex-addr 

-mic-compat 

-masm-compat 

-mno-strict-align 


o-soft-float -msoft-float 


-mfp-arg-in-gregs 


-mmips-as 

-mgpopt 


-mint64 -mlong64 

-mgas -mmames 

-mno-gpopt -mstats 


-mabicalls 


mno- shared- li bs - mlong- calls - mdisable-fpregs - mdisable- 


-mleaf-procedures 

-mno-tail-call 

-mcode-align 

-niic2.0-compat 

-mintel-asm 


Code-Generation Options 
-fcall-saved-reg -fcall-used- 
r e g -ffixed-reg -finhibit- 
size-directive -fnonnull- 
objects -fno-cominon -fno-ident 
-fno-gnu-linker -fpcc-struct- 
return -fpic -fPIC -freg- 
struot- return -fshared-data - 
fshort-enums -fshort-double - 
fvolatile -fvolatile-global - 
fverbose-asm 
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OVERALL OPTIONS 

-x language Specify explicitly the i anguage for the following input files (rather than choosing a default based on the 
filename suffix). This option applies to all following input files until the next -x option. Possible values of 
I anguage arec,objective-c, c-header, C++, cpp-output, assembler, and assembler-with-cpp. 

-x none T urn off any specification of a language, so that subsequent files are handled according to their fi lename 

suffixes (as they are if -xhasnot been used at all). 

If you want only some of the four stages (preprocess, compile, assemble, link), you can use -x (or filename suffixes) to tell gcc 
where to start, and one of the options -c, -s, or -e to say where gcc is to stop. N ote that some combinations (for example, -x 
cpp-output -e) instruct gcc to do nothing at all. 

-c Compile or assemble thesourcefiles, but do not link. The compiler output is an object file corresponding 

to each source file. 

By default, gcc makes the object filename for a source file by replacing the suffix . c,. t,. s, and so on, with 
.0. U se-o to select another name 

gcc ignores any unrecognized input files (those that do not require compilation or assembly) with the-c 
option. 

-s Stop after the stage of compilation proper; do not assemble. The output isan assembler codefilefor each 

nonassembler input file specified. 

By default, gcc makes the assembler filename for a source file by replacing the suffix .c, .i, and so on, with 

.s. Use-o to select another name 

gcc ignores any input files that don't require compilation. 

-e Stop after the preprocessing stage; do not run the compiler proper. The output is preprocessed source 

code, which is sent to the standard output, 
gcc ignores input files that don't require preprocessing. 

-o f i i e Place output in filef i i e. This applies regardless to whatever sort of output gcc isproducing, whether it be 

an executable file, an object file, an assembler file, or preprocessed C code. 

Since only one output file can be specified, it does not make sense to use -o when compiling more than 
oneinputfilq unless you are producing an executable file as output. 

If you do not specify-o, the default is to put an executable file in a.out, theobject filefor source .suffix in 
source .o, its assembler file in s our ce. s, and all preprocessed C source on standard output. 

-v Print (on standard error output) the commands executed to run thestagesof compilation. Also print the 

version number of the compiler driver program and of the preprocessor and the compiler proper. 

-pipe Use pipes rather than temporary files for communication between the various stages of compilation. This 

fails to work on some systems where the assembler cannot read from a pipe; but theGN U assembler has 
no trouble. 


LANGUAGE OPTIONS 

The following options control the dialect of C that the compiler accepts 
-ansi Support all AN SI standard C programs. 

This turns off certain features of GN U C that are incompatible with AN SI C, such as the asm, 
inline, and typeof keywords, and predefined macros such asunix and vax that identify thetype 
of system you are using. It also enables the undesirable and rarely used AN SI trigraph feature, 
and disallows® as part of identifiers. The alternate keywords__asm_, __extension_, 

_inline_, and __typeof_ continue to work despite-ansi. You would not want to use them 

in an ANSI C program, of course, but it is useful to put them in header files that might be 
included in compilations done with -ansi. Alternate predefined macrossuch as__unix_ and 
_vax_are also available, with or without -ansi. 

The -ansi option does not cause non-AN SI programs to be rq acted gratuitously. For that, - 
pedantic isrequired in addition to -ansi. 



fno-builtin 


fno-strict-prototype 

trigraphs 

traditional 


traditional-cpp 

fdollars-in-identifiers 

fenum-int-equiv 
fexternal-templates 


fall-virtual 


fcond-mismatch 

fthis-is-variable 

funsigned-char 


The preprocessor predefine a macro __strict_ansi_ when you use the-ansi option. Some 
header file may notice this macro and refrain from declaring certain functionsor defining 
certain macrosthattheAN SI standard doesn't call for; thisisto avoid interfering with any 
programs that might use these name for other things. 

Do not recognize asm, inline, or typeof asa keyword. These words may then be used as 
identifies. You can use__asm_, __iniine_, and __typeof_ instead, -ansi implie -fno-asm. 

D on't recognize built-in functionsthat do not begin with two leading underscore. C urrently, 
the functions affected include_exit, abort, abs, alloca, cos, exit, tabs, labs, memcmp, memcpy, 
sin, sqrt, strcmp, strcpy.and strlen. 

The -ansi option prevents aiioca and _exit from being built-in functions. 

T reat a function declaration with no arguments, such asint foot);, asC would treat it—as 
saying nothing about the numbe of arguments or their type (C ++only). N ormally, such a 
delaration in C ++means that the function too take no arguments. 

Support AN SI C trigraphs. The -ansi option implie -trigraphs. 

Attempt to support some aspects of traditional C compilers For details, see theGNU C 
Manual; the duplicate list here has been deleted so that we won't get complaints when itisout 
of date. 

But one note about C++programsonly (note), -traditional hasoneadditional effect for 
C ++: assignment to this is permitted. T his is the same as the effect of -f this-is-variabie. 
Attempt to support some aspects of traditional C preprocessors Thisindudes the items that 
specifically mention the preprocessor previously, but none of the other effects of -traditional. 
Permit the use of $ in identifiers (C-H-only). You can also use -fno-doiiars-in-identifiersto 
explicitly prohibit use of $. (G N U C ++ allows $ by default on some target systems but not 
others) 

Permit implicit conversion of mt to enumeration types (C-H-only). N ormally G N U C ++ 
allows conversion of enum to int, but not the other way around. 

Produce smaller code for template declarations by generating only a single copy of each 
tempi ate function where it isdefined (C++only). To usethisoption successfully, you must also 
mark all files that use templates with either #pragma implementation (the definition) or#pragma 
interface (declarations). 

When your code is compiled with -f external-templates, all template instantiations are external. 
You must arrange for all necessary instantiations to appear in the implementation file; you can 
do thiswith atypedef that references each instantiation needed. Conversely, when you compile 
using thedefault option -fno-externai-tempiates, all template instantiationsareexplicitly 
internal. 

Treat all possible member functionsas virtual, implicitly. All member functions (except for 
constructor functions and new or delete member operators) are treated as virtual functions of 
the class where they appear. This does not mean that all calls to these member functions will be 
made through the internal table of virtual functions. U nder some circumstances, the compiler 
can determinethatacall to agiven virtual function can be made directly; in these cases, the 
calls are direct in any case 

Allow conditional expressions with mismatched types in the second and third arguments The 
value of such an expression is void. 

Permit assignment to this (C ++only). The incorporation of user-defined free store manage 
ment into C++ has made assignment to this an anachronism. Therefore, by default it is invalid 
to assign to this within a class member function. However, for backwards compatibility, you 
can make it valid with -fthis-is-variabie. 

Ldt the type char be unsigned, like unsigned char. 

Each kindof machine has a default for what char should be. It is either like unsigned char by 
default or like signed char by default. 
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-fsigned-char 


-fsigned-bitfields 
-funsigned-bitfields 
-fno-signed-bitfields 


Ideally, a portable program should always use signed char or unsigned char when itdependson 
the signedness of an object. But many programs have been written to use plain char and expect 
it to be signed, or expect it to be unsigned, depending on the machines they were written for. 
This option, and its inverse lets you make such a program work with the opposite default. 

The type char is always a distinct type from each of signed char and unsigned char, even though 
its behavior is always just like oneof those two. 

Let the type char be signed, like signed char. 

N ote that this isequi valent to -f no-unsigned-char, which is the negative form Of -f unsigned- 
char. Likewise, -fno-signed-char is equivalent to -funsigned-char. 

These options control whether a bitfield is signed or unsigned, when declared with no explicit 
or unsigned qualifier. 

By default, such a bitfield is signed, because this is consistent: The basic integer types such as 


-fno-unsigned-bitfields signed are Signed types. 

H owever, when you specify -traditional, bitfields are all unsigned no matter what. 

-f writable-strings Store string constantsin the writable data segment and don't uniquize them. T his isfor 

compatibility with old programswhich assume they can write into string constants, -tradi¬ 
tional also has this effect. 

W riting into string constants is a very bad idea; constants should be constant. 


PREPROCESSOR OPTIONS 


These options control theC preprocessor, which is run on each C source file before actual compilation. 

If you use the -e option, gcc does nothing except preprocessing. Some of these options makesense only together with -e 
because they cause the preprocessor output to be unsuitable for actual compilation. 


-include 


-imacros 


-idirafter id 


-iprefix prefix 
-iwithpreflx dir 

-nostdinc 


Process f i i e asinput before processing the regular input file. In effect, the contents off i i e 
are compiled first. Any -d and -u options on the command line are always processed before 
-include f i i e, regardless of the order in which they are written. All the-include and -imacros 
options are processed in the order in which they are written. 

Process f i i e asinput, discarding the resulting output, before processing the regular input file 
Because the output generated from f i i e is discarded, the only effect of-imacros file is to make 
the macros defined inf i i e available for use in the main input. The preprocessor evaluates any 
-d and -u options on the command line before processing-imacros file, regardless of the order 
in which they are written. All the-include and -imacros options are processed in the order in 
which they are written. 

Add the di rectory di r to the second include path. The directories on the second include path 
are searched when a header file is not found in any of the directories in the main include path 
(the one that-i adds to). 

Specify prefix asthe prefix for subsequent -iwithpreflx options 

Add a directory to the second include path. The directory's name is made by concatenating 

pref i x and di r, where pr ef i x was specified previously with -iprefix, 

Do not search the standard system directories for header files. Only the directories you have 
specified with -i options (and the current directory, if appropriate) are searched. 

By using both -nostdinc and -i-, you can limit the include file search file to only those 
directories you specify explicitly. 

D o not search for header files in the C++-specific standard directories, but do still search the 
other standard directories (Thisoption isused when building iibg++.) 

Do not predefine any nonstandard macros (including architecture flags). 

Run onlytheC preprocessor. Preprocess all theC source files specified and output the results to 

standard output or to the specified output file 

Tell the preprocessor not to discard comments. Used with the-E option. 



-Aquest i on(answer ) 


-Aquest i on ( answer 




r o =def n 


ASSEMBLER OPTION 

-Wa.option 


Tell the preprocessor not to generate #iine commands. U sed with the -e option. 

Tell the preprocessor to output a rule suitable for make describing the dependencies of each 
object file For each source file, the preprocessor outputs one make -rule whose target is the 
object filename for that source file and whose dependencies are all the files that have been 
included with #inciude. This rule may be a single line or may be continued with \-newline if it 
is long. The list of rules is printed on standard output instead of the preprocessed C program. 

-m implies -e. 

-mg says to treat missing header files as generated files and assume they live in the same directory 
as the source file It must be specified in addition to -m. 

Like-Mbuttheoutput mentionsonlytheuserheaderfilesinduded with #inciude ■ file n . 
System header files included with #inciude < file > are omitted. 

Like -m but the dependency information is written to files with names made by replacing .0 
with .d at the end of the output filenames. This is in addition to compiling the file as specified; 
-md does not inhibit ordinary compilation theway -m does. 

The Mach utility md can be used to merge the .d files into a single dependency file suitable for 
using with the make command. 

Like -md except mention only user header files, not system header files. 

Print the name of each header file used, in addition to other normal activities. 

Assert the answer answer for quest ion, in case it is tested with a preprocessor conditional such as 
#if #quest i on (answer >. -a- disables the standard assertions that normally describe the target 
machine. 

Assert the answer answer for quest ion, in case it is tested with a preprocessor conditional such as 
#if # question ( answer >. -A-disables the standard assertions that normally describe the target 
machine. 

Define macro macro with the string 1 as its definition. 

D efi ne macro ma c r 0 as d e f n . Al I instances of -d on the command line are processed before any 
-u options. 

U ndefine macro ma c r 0 . -u options are evaluated after all -d options, but before any -include and 
-imacros Options. 

T ell the preprocessor to output only a list of the macro definitions that are in effect at the end 
of preprocessing. U sed with the -e option. 

Tell the preprocessor to pass all macro definitions into the output, in their proper sequence in 
the rest of the output. 

Like -dD except thatthe macro arguments and contents are omitted. Only#define name is 
included in theoutput. 


Passopti on as an option to the assembler. If opt i on contains commas, it issplit into multiple 
options at the commas. 


LINKER OPTIONS 

These options come into play when the compiler links object files into an executable output file. They are meaningless if the 

compiler is not doing a link step. 

obj ect-fi 1 e- name A filenamethat does not end in a special recognized suffix is considered to name an object file 

or library. (0 bject files are distinguished from libraries by the linker according to thefile 
contents.) If gcc does a link step, these object files are used as input to the linker. 

-11 i br a r y Usethe library named 1 i brary when linking. 

The linker searches a standard list of directories for the library, which is actually a file named 
nb 1 i brary .a. T he linker then usesthisfileasif it had been specified precisely byname. 
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-lobjc 

-nostartfiles 

-nostdlib 

-shared 

-symbolic 

-Xlinker option 


The directories searched include several standard system directories plusany that you specify 
with -l. 

Normally, the files found this way are library files-archive files whose members are object files 
The linker handles an archive file by scanning through it for members that define symbols that 
have so far been referenced but not defined. However, if the linker finds an ordinary object file 
rather than a library, the object file is linked in the usual fashion. The only difference between 
using an -1 option and specifying a filename is that-I surrounds i i br ary with lib and .a and 
searches several directories. 

You need thisspecial case of the -1 option in order to link an Objective C program. 

Do not use the standard system startup files when linking. Thestandard libraries are used 
normally. 

Don't use the standard system libraries and startup files when linking. Only thefiles you specify 
will be passed to the linker. 

On systems that support dynamic linking, this prevents linking with the shared libraries. On 
other systems, this option has no effect. 

Produce a shared object which can then be linked with other objects to form an executable 
0 nly a few systems support this option. 

Bind references to global symbols when building a shared object. W arn about any unresolved 
references (unless overridden by the link editor option-xiinker -z -xiinker defs). Only a few 
systems support this option. 

Pass option as an option to the linker. You can use this to supply system-specific linker options 
which G N U CC does not know how to recognize. 

If you want to pass an option that takes an argument, you must use-xiinker twice: once for the 
option and once for the argument. For example, to pass-assert definitions, you must write- 
Xiinker -assert -Xiinker definitions. It does not Work to Write-Xiinker "-assert 
definitions", because this passes the entire string as a single argument, which is not what the 
linker expects. 

Pass option as an option to the linker. If option contains com mas, it is split into multiple 
options at the commas. 

Pretend the symbol symbol is undefined, to force linking of library modules to define it. You 
can use-u multiple times with different symbols to force loading of additional library modules 


DIRECTORY OPTIONS 

These options specify directories to search for header files, for libraries, and for parts of the compiler: 

-idi r Append directory di r to the list of directories searched for include files 

-i- Any directories you specify with -i options before the-i- option aresearched only for the case 

of #inciude 11 f ii e they are not searched for include <fiie>. 

If additional directories are specified with -i options after the -i-, these directories are searched 
for all #inciude directives. (0 rdinarily all -i directories are used thisway.) 

In addition, the-i- option inhibits the use of the current directory (where the current input file 
came from) as the first search directory for #inciude ■ file ".There is no way to override this 
effect of -i-. With -i. you can specify searching the directory that was current when the 
compi ler was invoked. T hat is not exactly the same as what the preprocessor does by default, 
but it is often satisfactory. 

-i- does not inhibit theuse of thestandard system directories for header files. Thus, -i- and 
-nostdinc are independent. 

-Ldi r Add directory di r to the list of directories to besearched for-i. 

-Bpref i x This option specifies where to find the executables, libraries, and data files of the compiler itself. 

The compiler driver program runs one or more of the subprograms cpp, cci (or, for C++, 
ccipius), as, and id. It tries pref i x as a prefix for each program it tries to run, both with and 
Without mac hi tie / version /. 
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For each subprogram to be run, the compiler driver first tries the -b prefix, if any. If that name 
is not found, or if -b was not specified, the driver tries two standard prefixes, which are /usr/ 
iib/gcc/ and /usr/iocai/iib/gcc-iib/. If neither of those results in a filenamethat isfound, the 
compiler driver searches for the unmodified program name, using the directories specified in 
your path environment variable 

The runtime support file nbgcc.a is also searched for using the -b prefix, if needed. If it is not 
found there the two standard prefixes (preceding paragraph) are tried, and that is all. The file is 
left out of the link if it is not found by those means. M ost of the time, on most machines, 
nbgcc.a is not actually necessary. 

You can get a similar result from the environment variable gcc_exec_prefix; if it isdefined, its 
value is used as a prefix in the same way. If both the-B option and theGcc_EXEC_PREFix variable 
are present, the-B option isused first and the environment variable value second. 


WARNING OPTIONS 


W arningsare diagnostic messages that report constructions that are not inherently erroneous but are risky or suggest there 
may have been an error. 

T hese options control the amount and ki nds of warni ngs produced by G N U C C: 


-fsyntax-only 

-Wno-import 

-pedantic 


C heck the code for syntax errors, but don’t emit any output. 

Inhibit all warning messages. 

Inhibit warning messages about the use of #import. 

Issue all the warni ngs demanded by strict ANSI standard C; reject all programs that use 
forbidden extensions. 

Valid AN SI standardC programs should compile properly with or without this option (though 
a rare few will require-ansi). However, without this option, certain GNU extensionsand 
traditional C features are supported as well. W ith this option, they are rqected. T here is no 
reason to usethisoption; it exists only to satisfy pedants. 

-pedantic does not cause warning messagesfor use of the alternate keywords whose names begin 
and end with Pedantic warnings are also disabled in the expression that follows extension. 

H owever, only system header files should use these escape routes; application programs should 
avoid them. 

Like -pedantic, except that errors are produced rather than warnings. 

Print extra warning messages for these events 

A nonvolatile automatic variable might be changed by acall to longjmp. These warnings are 
possible only in optimizing compilation. The compiler sees only the calls to setjmp. It cannot 
know where long jmp will be called; in fact, a signal handler could call it at any point in the code. 
Asa result, you may get a warning even when there is in fact no problem because longjmp 
cannot in fact be called at the place which would cause a problem. 

A function can return either with or without a value. (Falling off the end of the function body 
is considered returning without a value.) For example, this function would evoke such a 
warning: 
foo (a) 


if (a > 0) 


Spurious warnings can occur because G N U CC does not realize that certain functions 
(including abort and longjmp) will never return. 

An expression-statement or the left side of a comma expression contains no side effects To 
suppress the warning, cast the unused expression to void. For example, an expression such as 
x[i,j] will cause a warning, but x[(void)i,j] will not. 

An unsigned value is compared against zero with > or <=. 
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-Wreturn-type 

-Wunused 


-Wswitch 


-Wcomment 

-Wtrigraphs 

-Wformat 

-Wchar-subscripts 

-Wuninitialized 


Warn whenever a function or parameter is implicitly declared. 

Warn whenever a function isdefined with a return-type that defaults to int. Also warn about 
any return Statement with no return -value in a function whose return - type is not void. 

W arn whenever a local variable is unused aside from its declaration, whenever a function is 
declared static but never defined, and whenever a statement computes a result that isexplicitly 
not used. 

Warn whenever a switch statement has an index of enumeral type and lacks a case for one or 
more of the named codes of that enumeration. (The presence of a default label prevents this 
warning.) case labels outside the enumeration range also provokewarningswhen thisoption is 
used. 

W arn whenever a comment-start sequence / appears in a comment. 

Warn if any trigraphs are encountered (assuming they are enabled). 

Check calls to printf and scant, and so on, to make sure that the arguments supplied have 
types appropriate to theformat string specified. 

Warn if an array subscript has type char. This is a common cause of error, as programmers 
often forget that thistype issigned on some machines. 

An automatic variable is used without first being initialized. 

These warnings are possible only in optimizing compilation, because they require data flow 
information that is computed only when optimizing. If you don't specify-o, you simply won't 
get these warnings 

These warnings occur only for variables that are candidates for register allocation. Therefore, 
they do not occur for a variable that is declared volatile or whose address istaken, or whose size 
is other than 1,2,4, or 8 bytes Also, they do not occur for structures unions, or arrays even 
when they are in registers 

N ote that there may be no warning about a variable that is used only to compute a value that 
itself is never used, because such computations may be deleted by data flow analysis before the 
warnings are printed. 

These warnings are made optional becauseGNU CC is not smart enough to see all the reasons 
why the code might be correct despite appeari ng to have an error. H ere is one example of how 
this can happen: 



switch (y) 


} 

too (x); 

If the value of y is always i, 2, or 3, then x is always initialized, but GNU CC doesn't know this. 
H ere is another common case: 

int save_y; 

if (change_y) save_y =y,y =new_y; 
if (change_y)y =save_y; 

T his has no bug because save_y is used only if it is set. 

Some spuriouswarnings can be avoided if you declare as volatile all the functions you use that 
never rdturn. 
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-wparentheses W arn if parentheses are omitted in certain contexts 

-wtempiate-debugging When using templates in a C++ program, warn if debugging is not yet fully available (C++ 
only). 

-wan All of the preceding -w options combined. These are all the options that pertain to usage that 

we recommend avoiding and that we believe iseasy to avoid, even in conjunction with macros 

The remaining-w... options are not implied by-waii because they warn about constructions that we consider reasonable to 
use, on occasion, in clean programs. 




-Wshadow 
-Wid-clash-l en 

-Wpointer-arith 


-Wwrite-strings 


-Wconversion 

-Waggregate-return 

-Wstrict-prototypes 

-Wmissing-prototypes 

-Wmissing-declarations 

-Wredundant-decls 

-Wnested-externs 


Warn about certain constructs that behave differently in traditional andANSI C: 

M aero arguments occurring within string constants in the macro body. These would substitute 
the argument in traditional C, but are part of the constant in AN SI C. 

A function declared external in one block and then used after theend oftheblock. 

A switch statement has an operand of type long. 

W arn whenever a local variable shadows another local variable. 

Warn whenever two distinct identifiers match in the first i en characters This may help you 
prepare a program that will compile with certain obsolete, brain-damaged compilers. 

W arn about anything that depends on the size of a function type or of void. G N U C assigns 
these typesa size of i, for convenience in calculations with void pointers and pointers to 
functions 

W arn whenever a pointer is cast so as to remove a type qualifier from the target type. For 
example, warn if a const char is cast to an ordinary char. 

Warn whenever a pointer is cast such that the required alignment of thetarget is increased. For 
example, warn if a char is cast to an int on machines where integers can only be accessed at 
two- or four-byte boundaries 

Give string constantsthetype const char[ length ] so that copying the addressof one into a 
non-const char pointer will get a warning. These warnings will help you find at compiletime 
code that can try to write into a string constant, but only if you have been very careful about 
using const in declarations and prototypes Otherwise, it will just be a nuisance; this is why we 
did not make -wail request these warnings. 

W arn if a prototype causes a type conversion that is different from what would happen to the 
same argument in theabsence of a prototype. T his includes conversions of fixed point to 
floating and vice versa, and conversions changing the width or signedness of a fixed point 
argument except when the same as the default promotion. 

Warn if any functions that return structures or unions are defined or called. (In languages 
where you can return an array, this also elicitsa warning.) 

Warn if a function is declared or defined without specifying the argument types (An old-style 
function definition is permitted without a warning if preceded by a declaration which specifies 
the argument types.) 

W arn if a global function is defined without a previous prototype declaration. This warning is 
issued even if the definition itself provides a prototype. The aim is to detect global functions 
that fail to be declared in header files. 

Warn if a global function isdefined without a previous declaration. Dosoeven if the definition 
itself provides a prototype. U sethis option to detect global functionsthat are not declared in 
header files 

Warn if anything is declared more than once in the same scope, even in cases where multiple 
declaration is valid and changes nothing. 

Warn if an extern declaration isencountered within an function. 


-wenum-ciash Warn about conversion between different enumeration types (C++only). 

-woverioaded-virtual (C++only.) In a derived class the definitionsof virtual functions must match the type signature 
of a virtual function declared in the base class Use this option to request warnings when a 
derived class declares a function that may bean erroneous attempt to define a virtual function; 
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that is, warn when there is a function with the same name as a virtual function in the base class, 
but with a type signature that doesn't match any virtual functions from the base class 

-winiine Warn if a function cannot be inlined, and either it was declared as inline or else the -f inline- 

functions option was given. 

-werror T reat warnings as errors; abort compilation after any warning. 

DEBUGGING OPTIONS 

G N U CC has various special optionsthat are used for debugging either your program or gcc: 

-g Produce debugging information in the operating system's native format (stabs COFF, XCO FF, 

or DWARF). GDB (theGNU debugger) can work with thisdebugging information. 

On mostsyStemsthatusestabsformat, -g enables use of extra debugging information thatonlyGDB 
can use; this extra information makes debugging work better in G D B but will probably make 
other debuggers crash or refuse to read the program. If you want to control for certain whether 
to generate the extra information, use -gstabs, -gstabs, -gxcoff+, -gxcoff, -gdwarf+, or -gdwarf. 
Unlike most other C compilersGNU CC allows you to use-g with -o. The shortcuts taken by 
optimized code may occasionally produce surprising results: Some variables you declared may 
not exist at all; flow of control may briefly move where you did not expect it; some statements 
may not be executed because they compute constant results or their values were already at hand; 
some statements may execute in different places because they were moved out of loops. 
Nevertheless, it proves possible to debug optimized output. This makes it reasonable to use the 
optimizer for programs that might have bugs. 

The following options are useful when GN U CC is generated with the capability for more than one debugging format. 

-ggdb Produce debugging information in the native format (if that is supported), including GDB 

extensions if at all possible. 

-gstabs Produce debugging information in stabs format (if that is supported), without GDB exten¬ 

sions. Thisistheformat used by D BX on most BSD systems. 

-gstabs+ Produce debugging information in stabs format (if that is supported), using GN U extensions 

understood only by theGN U debugger (GDB). The use of these extensions is likely to make 
other debuggers crash or refuse to read the program. 

-gooff Produce debugging information in COFF format (if that issupported). Thisistheformat used 

by SD B on most System V systems prior to System V Release 4. 

-gxcoff Produce debugging information in XCOFF format (if that issupported). Thisistheformat 

used bytheDBX debugger on IBM R S/6000 systems. 

-gxcoff + Produce debugging information in XCO FF format (if that issupported), using GNU 

extensions understood only by the G N U debugger (G D B). T he use of these extensions is likely 
to make other debuggers crash or refuse to read the program. 

-gdwarf Produce debugging information in DWARF format (if that issupported).Thisistheformat 

used by SD B on most System V Release 4 systems. 

-gdwarf + Produce debugging information in DWARF format (if that is supported), using GN U 

extensions understood only by the G N U debugger (G D B). T he use of these extensions is likely 
to make other debuggers crash or refuse to read the program. 

-glevel 
-gstabsl e v e I 

-gcoffI e v e I -gxcoffI e v eI 

-gdwarfi evei Request debugging information and also usei evei to specify how much information. The 

default level is 2. 

Level 1 produces minimal information, enough for making backtraces in parts of the program 
that you don't plan to debug. This includes descriptions of functions and external variables but 
no information about local variables and no line numbers 
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FI 


dD 

dy 


dl 

dg 


dJ 


dp 

fpretend-float 


print-libgcc-file-name 
print-prog-name=p r o g r a m 


Le/el 3 includes extra information, such as all the macro definitions present in the program. 
Some debuggers support macro expansion when you use-g3. 

Generate extra code to write profile information suitable for the analysis program prof. 
Generate extra code to write profile information suitable for the analysis program gprof. 
Generate extra code to write profile information for basic blocks, which will record the number 
of times each basic block isexecuted. Thisdata could be analyzed by a program liketcov. N ote, 
however, that the format of the data is not what tcov expects Eventually, GNU gprof should 
be extended to process thisdata. 

Saysto makedebugging dumps during compilation at times specified byi etters. This is used 
for debugging the compiler. T he filenames for most of the dumps are made by appending a 
word to the source fi lename (for example, foo.c.rti or foo.c.j ump). 

D ump all macro definitions at the end of preprocessing, and write no output. 

D ump all macro names at the end of preprocessing. 

Dump all macro definitions at the end of preprocessing, in addition to normal output. 

D ump debugging information during parsing, to standard error. 

D ump after RTL generation, to f i i e. rti. 

J ust generate RT L forafunction instead of compiling it. Usually used with r. 

Dump after first jump optimization, to f i i e . jump. 

Dump after CSE (including the jump optimization that sometimes follows CSE), to f i i e . cse. 
D ump after loop optimization, to f i i e . loop. 

D ump after the second C SE pass (including the jump optimization that sometimesfollows 
CSE), to f i I e . cse2. 

D ump after flow analysis to f i i e . flow. 

D ump after instruction combination, to f i i e . combine. 

D ump after thefirst instruction scheduling pass, to f i i e . sched. 

D ump after local register allocation, to f i i e . ireg. 

D ump after global register allocation, to f i i e . greg. 

Dump after the second instruction scheduling pass to f i e .sched 2 . 

Dump after last jump optimization, to f i i e . jump 2 . 

D ump after delayed branch scheduling, to f i i e .dbr. 

D ump after conversion from registers to stack, to f i i e . stack. 

Produce all the dumps listed previously. 

Print statistics on memory usage, at the end of the run, to standard error. 

Annotate the assembler output with a comment indicating which pattern and alternative was 
used. 

When running a cross-compiler, pretend that the target machine uses the same floating-point 
format as the host machine This causes incorrect output of the actual floating constants, but 
the actual instruction sequence will probably be the same asGN U CC would make when 
running on the target machine 

Store the usual temporary intermediate files permanently; place them in the current directory 
and name them based on the source file Thus, compiling foo.c with -c -save-temps would 
produce files f oo. cpp and foo.s, as well asfoo.o. 

Print the full absolute name of the library file i i brary would be used when linking, and do not 
do anything else. W ith thisoption, G N U CC does not compileor link anything; it just prints 
thefilename. 

Same as - print-file-name=libgcc. a. 

Like -print-fiie-name, but searches for a program such as cpp. 
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OPTIMIZATION OPTIONS 

These options control various sorts of optimizations: 

-o, -01 Optimize Optimizing compilation takes somewhat more time, and a lot more memory for a 

large function. 

Without -o, the compiler’s goal is to reduce the cost of compilation and to make debugging 
produce the expected results. Statements are independent: If you stop the program with a 
breakpoint between statements, you can then assign a new value to any variable or change the 
program counter to any other statement in the function and get exactly the results you would 
expect from the source code. 

W ithout -o, only vari ables declared register are allocated in registers. T he resulting compiled 
code is a little worse than produced by PCC without-o. 

W ith -o, the compiler tries to reduce code size and execution time. 

W hen you specify -o, the two options -f thread-j umps and -f def er-pop are turned on. 0 n 
machinesthat have delay slots, the-fdeiayed-branch option is turned on. For those machines 
that can support debugging even without a frame pointer, the -fomit-frame-pointer option is 
turned on. On some machines other flags may also be turned on. 

-02 Optimizeeven more Nearly all supported optimizationsthatdo not involve a space-speed 

tradeoff are performed. Loop unrolling and function inlining are not done for example As 
compared to -o, thisoption increases both compilation time and the performance of the 
generated code 

-03 0 ptimizeyet more. Thisturnson everything -02 does, along with also turning on -f inline- 

functions. 

-00 Do not optimize 

If you use multiple-0 options, with or without level numbers, the last such option is the one 
that is effective 

Options of the form -f flag specify machineindependent flags Most flags have both positive and negative forms; the 
negative form of -ff 00 would be -f no-foo. T he following list shows only one form— the one which is not the default. You 
can figure out the other form by either removing no- or adding it. 

-ffioat-store Do not store floating-point variables in registers. This prevents undesirable excess precision on 

machines such as the 68000 where the floating registers (of the 68881) keep more precision 
than a double is supposed to have. 

For most programs, theexcess precision does only good, but a few programs rely on the precise 
definition of IEEE floating point. Use-ffioat-store for such programs 
-fmemorize-iookups U se heuristics to compilefaster (C -n-only). These heuristics are not enabled by default, 

-fsave-memorized since they are only effective for certain inputfiles Other input files compile more slowly. 

Thefirst time the compiler must build a call to a member function (or reference to a data 
member), it must (1) determine whether the class implements member functions of that name; 
(2) resolve which member function to call (which involves figuring out what sorts of type 
conversions need to be made); and (3) check the visibility of the member function to the caller. 
All of this adds up to slower compilation. N ormally, the second time a call is made to that 
member function (or reference to that data member), it must go through the same lengthy 
process again. This means that code like this: 

cout « "This " « p « "has"« \ « " legs.\n" 

makes six passes through all three steps. By using a software cache a hit significantly reduces 
thiscost. Unfortunately, using the cache introduces another layer of mechanisms which must 
be implemented, and so incursitsown overhead, -fmemorize- lookups enables the software 
cache 

Because access privileges (visibility) to members and member functions may differ from one 
function context to the next, g++ may need to flush the cache. W ith the -fmemorize-iookups 
flag, the cache isflushed after every function that is compiled. The -fsave-memorized flag 
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-fno-default-inline 

-fno-defer-pop 


-fforce-mem 


-fforce-addr 


-fomit-frame-pointer 


-fkeep-inline-functions 

-fno-function-cse 


enables the same software cache, but when the compiler determi nes that the context of the last 
function compiled would yield thesame access privileges of the next function to compile it 
preserves the cache. T his is most helpful when defining many member functionsfor the same 
class: with the exception of member functions which are friends of other classes, each member 
function has exactly the same access privilege as every other, and the cache need not be flushed. 
D on't make member functions inline by default merely because they are defined inside the class 
scope(C-H-only). 

Always pop the arguments to each function call as soon as that function returns For machines 
which must pop arguments after a function call, the compiler normally lets arguments 
accumulate on the stack for several function callsand pops them all at once. 

Force memory operands to be copied into registers before doing arithmetic on them. This may 
produce better code by making all memory references potential common subexpressions W hen 
they are not common subexpressions, instruction combination should eliminate the separate 
register-load. I am interested in hearing about the difference thismakes. 

Force memory address constants to be copied into registers before doing arithmetic on them. 
This may produce better code just as-fforce-mem may. I am interested in hearing about the 
difference this makes. 

Don't keep the frame pointer in a register for functions that don't need one. This avoids the 
instructions to save, set up and restore frame pointers; it also makes an extra register available in 
many functions. It also makes debugging impossibleon most machines 
On some machines, such as the VAX, thisflag has no effect because the standard calling 
sequence automatically handles the frame pointer and nothing issaved by pretending it doesn't 
exist. The machine-description macro frame_pointer_required controls whether a target 
machine supports thisflag. 

Integrate all simple functions into their callers. The compiler heuristi cally decides which 
functions are simple enough to be worth integrating in thisway. 

If all calls to a given function are integrated, and the function is declared static, then gcc 
normally does not output the function as assembler code in its own right. 

Enable values to be allocated in registers that will be clobbered by function calls, by emitting 
extra instructions to save and restore the registers around such calls Such allocation is done 
only when it seems to result in better code than would otherwise be produced. 

This option is enabled by default on certain machines, usually those which have no call- 
preserved registers to use instead. 

Even if all calls to a given function are integrated, and thefunction isdeclared static, 
nevertheless output a separate runtime callable version of thefunction. 

D o not put function addresses in registers make each instruction that calls a constant function 
contain the function's address explicitly. 

Thisoption results in less efficient code, but some strange hacks that alter theassembler output 
may be confused by the optimizations performed when thisoption isnot used. 

D isable any machine-specific peephole optimizations. 

Thisoption allows gcc to violate some AN SI or IEEE specifications in the interest of optimiz¬ 
ing code for speed. For example, it allows the compiler to assume arguments to the sqrt 
function are nonnegative numbers 

Thisoption should never be turned on by any -o option because it can result in incorrect 
output for programs which depend on an exact implementation of IEEE or AN SI rule^ 
specifications for math functions 


Thefollowing options control specific optimizations The-02 option turns on all of these optimizations except -funroii- 
loops and -funroll-all-loops. 

The-o option usually turns on the-fthread-jumps and -fdeiayed-branch options but specific machines may change the 
default optimizations. 
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You can use thefollowing flags in the rare cases when fine-tuning of optimizations to be performed isdesired: 


-fstrength-reduce 
-fthread-jumps 


-funroll-loops 
-funroll-all-loops 
-fcse-follow-jumps 


-fcse-skip-blocks 


-frerun-cse-after-loop 

-felide-constructors 


-fexpensive-optimizations 
-fdelayed-branch 

-fschedule-insns 


-fschedule-insns2 


Perform the optimizations of loop strength reduction and elimination of iteration variables. 
Perform optimizations where we check to see if a jump branches to a location where another 
comparison subsumed by thefirst isfound. If so, thefirst branch is redirected to either the 
destination of the second branch or a point immediately following it, depending on whether 
the condition is known to be true or false. 

Perform the optimization of loop unrolling. This isonly donefor loops whose number of 
iterationscan be determined at compile timeor runtime 

Perform the optimization of loop unrolling. This is done for all loops. This usually makes 
programs run more slowly. 

In common subexpression elimination, scan through jump instructions when the target of the 
jump is not reached by any other path. For example, when CSE encounters an if statement 
with an else clause, CSE will follow thejump when the condition tested isfalse 
This is similar to -fcse-foiiow-jumps, but causes CSE to follow jumps which conditionally skip 
over blocks W hen C SE encounters a si mple if statement with no else clause, -f cse-skip- 
biocks causes C SE to follow thejump around the body of the if. 

Rerun common subexpression elimination after loop optimizations has been performed. 

Elide constructors when this seems plausible (C-H-only). With this flag, GN U C++initializes y 
directly from the call to foo without going through a temporary in thefollowing code: 

A foo (); A y =foo (); 

W ithout this option, G N U C ++first initializesy by calling the appropriate constructor for type 
A; then assigns the result of foo to a temporary; and, finally, replaces the initial value of y with 
the temporary. 

T he default behavior (-fno-eiide-constructors) is specified by the draft AN SI C++standard. If 
your program's constructors have side effects, using -feiide-constructors can make your 
program act differently, since some constructor calls may be omitted. 

Perform a number of minor optimizations that are relatively expensive. 

If supported for the target machine, attempt to reorder instructionsto exploit instruction slots 
available after delayed branch instructions 

If supported for the target machine, attempt to reorder instructionsto eliminate execution stalls 
due to required data being unavailable This helps machines that have slow floating point or 
memory load instructions by allowing other instructionsto be issued until the result of the load 
or floating point instruction is required. 

Similar to -fscheduie-insns, but requests an additional pass of instruction scheduling after 
register allocation has been done This is especially useful on machines with a relatively small 
number of registers and where memory load instructions take more than one cycle. 


TARGET OPTIONS 

Bydefault, GN U CC compiles code for the same type of machine that you are using. 

However, it can also be installed as a cross-compiler, to compile for some other type of machine In fact, several different 
configurations of GN U CC, for different target machines, can be installed side by side. Then you specify which one to use 
with the-b option. 

In addition, older and newer versions of GN U CC can be installed side by side. One of them (probably the newest) will be 
the default, but you may sometimes want to use another. 

-b machine The argument mac hi ne specifiesthe target machinefor compilation. This is useful when you 

have installed GNU CC as a cross-compiler. 

The value to usefor mac hi ne is the same as was specified asthemachinetypewhen configuring 
GNU CC asa cross-compiler. For example, if a cross-compiler was configured with configure 



i386v, meaning to compile for an 80386 running System V, then you would specify -b i386v to 
run that cross compiler. 

When you do not specify -b, it normally meansto compileforthesametypeof machine that 
you are using. 

-v version Theargument ver s i on specifies which version of GNU CC to run. Thisisuseful when multiple 

versi on s are i n stal I ed. For example, ver s i on might be2.0, meaning to run GN U CC version 

2 . 0 . 

The default version, when you do not specify-v, is controlled by the way GN U CC is installed. 
Normally, it will bea version that isrecommended for general use. 


MACHINE-DEPENDENT OPTIONS 


Each of the target machine types can have its own special options, starting with -m, to choose among various hardware 
models or configurations— for example, 68010 versus 68020, floating coprocessor or none A single installed version of the 
compiler can compile for any model or configuration, according to theoptionsspecified. 

Some configurations of the compiler also support additional special options, usually for command-line compatibility with 
other compilers on thesame platform. 

T hese are the -m options defi ned for the 68000 series: 

-m68000 G enerate output for a 68000. This is the default when the compiler is configured for 68000- 

-mc68000 based systems. 

-m68020 Generate output for a 68020 (rather than a 68000). This is the default when the compiler is 

-mc68020 configured for 68020-based systems. 

—m6888i Generate output containing 68881 instructions for floating point. This isthe default for most 

68020-based systems unless -nfp was specified when the compiler was configured. 

-m68030 G enerate output for a 68030. T his is the default when the compiler is configured for 68030- 

based systems. 

-m68040 G enerate output for a 68040. T his is the default when the compiler is configured for 68040- 

based systems. 


-m68020“40 Generate output for a 68040, without using any of the new instructions. This results in code 

which can run relatively efficiently on either a 68020/68881 or a 68030 or a 68040. 

-mfpa Generate output containing Sun FPA instructions for floating point. 

-msoft-fioat Generate output containing library callsfor floating point. 


WARNING 


The requisite librariesare not part ofGNU CC. Normally, thefacilitiesof themachinefs usual C compiler are used, but 
thiscan’t bedonedirectly in cross-compilation. You must makeyour own arrangements to provide suitable library func¬ 
tions for cross-compilation. 


-mshort Considertype int to bel6bitswide like short int. 

-mnobitf ieid D o not use the bit-field instructions -1168000 implies -mnobitf ieid. 

-mbitfieid D o use the bit-field instructions. -m68020 implies -mbitfieid. This is the default if you use the 

unmodified sources. 

-mrtd Use a different function-calling convention, in which functions that take a fixed number of 

arguments return with thertd instruction, which pops their arguments while returning. This 
saves one instruction in the caller since there is no need to pop the arguments there. 

This calling convention is incompatible with the one normally used on UN IX, so you cannot 
use it if you need to call libraries compiled with the U NIX compiler. 
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Also, you must provide function prototypes for all functions that take variable numbers of 
arguments (including printf); otherwise incorrect code will be generated for calls to those 
functions 

In addition, seriously incorrect code will result if you call a function with too many arguments 
(N ormally, extra arguments are harmlessly ignored.) 

The rtd instruction is supported by the 68010 and 68020 processors but not by the 68000. 
These-m options are defined for the VAX: 

-munix D o not output certain jump instructions (aobieq and so on) that the U NIX assembler for the 

VAX cannot handle across long ranges 

-mgnu D o output those jump instructions on the assumption that you will assemble with theGN U 

assembler. 

-mg O utput codefor g-format floating-point numbers instead of d-format. 

T hese -m switches are supported on the sparc: 

-mfpu Generate output containing floating-point instructions. This isthe default. 

-mhard-float 

-mno-fpu Generate output containing library callsfor floating point. 

-msoft-float 


WARNING 


There is no GN U floating-point library for SPARC. Normally, the facilities of the machine's usual C compiler are used, 
but thiscannot be done directly in cross-compilation. You must make your own arrangements to provide suitablelibrary 
functionsfor cross-compilation. 


-msoft-float 

-mno-epilogue 

-mepilogue 


-mcypress 

-msupersparc 


Changes the calling convention in the output file; therefore it isonly useful if you compilea// 
of a program with this option. 

With -mepilogue (the default), the compiler always emits code forfunction exit at the end of 
each function. Any function exit in the middle of the function (such as a return statement in C) 
will generate a jump to the exit code at the end of the function. With -mno-epiiogue, the 
compiler tries to emit exit code inline at every function exit. 

These threeoptionsselect variationson the SPARC architecture. By default (unless specifically 
configured for the Fujitsu SPARCIite), gcc generates code for thev7 variant of the SPARC 
architecture. 

-mvs will give you SPARC v8 code The only difference from v7 codeisthat the compiler emits 
the integer multiply and integer divide instructionsthat exist in SPARC v8 but not in SPARC v7. 
-msparciite will giveyou SPARCIitecode This adds the integer multiply, integer divide step 
and scan (ffs) instructionsthat exist in SPARCIite but not in SPARC v7. 

T hese two options select the processor for which the code is optimized. 

With -mcypress (the default), the compiler optimizes code for theCypressCY7C602 chip, as 
used in theSparcStation and SparcServer 3xx series This is also appropriate for the older 
SparcStation 1, 2,1PX, and so on. 

With -msupersparc the compiler optimizes codefor the SuperSparc cpu, as used in the 
SparcStation 10,1000, and 2000 series. Thisflag also enables use of the full SPARC v8 
instruction set. 


T hese - m options are defined for the C onvex: 

-mci Generate output for a C1. This is the default when the compiler is configured for a C1. 

-mc2 G enerate output for a C 2. T his isthe default when the compiler is configured for a C 2. 
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-margcount Generate code which puts an argument count in the word preceding each argument list. Some 

nonportable Convex and VAX programs need thisword. (Debuggers don't, except for 
functions with variable-length argument lists; this information isin the symbol table.) 
-mnoargcount 0 mit the argument count word. This is the default if you use the unmodified sources 


These-m optionsare defined for the AM D Am29000: 





-mlarge 

-m29050 

-m29000 

-mkernel-registers 


-muser-registers 


G enerate code that assumes the D W bit is set, that is that byte and half-word operations are 
directly supported by the hardware. This is the default. 

G enerate code that assumes the D W bit is not set. 

Generate code that assumes the system supports byte and halfword write operations. Thisisthe 
default. 

G enerate code that assumes the systems does not support byte and halfword write operations. 
This implies-mnodw. 

Useasmall memory model that assumes that all function addresses are either within a single 
256KB segment or at an absolute address of less than 256K. This allows the can instruction to 
be used instead of a const, consth, cam sequence 
D o not assume that the can instruction can be used; this is the default. 

Generate code for theAm29050. 

Generate code for the Am29000. This is the default. 

Generate references to registers gr64-gr95 instead of gr96-gri27. This option can be used when 
compiling kernel code that wants a set of global registers digoint from that used by user-mode 
code. 

Note that when this option is used, register name in -f flags must use the normal, user-mode, 
names. 

Use the normal set of global registers, gr96-gri27. Thisisthe default. 

Insert a call to msp check after each stack adjustment. Thisisoften used for kernel code. 


T hese -m options are defi ned for M otorola 88K architectures: 


-m88000 

-m88100 

-IK88110 

-midentify-revision 

-mno-underscores 

-mcheck-zero-dlvision 

-mno-check-zero-division 


Generate code that works well on both them88100 and them88110. 

Generate code that works best for the m88100, but that also runs on them88110. 

Generate code that works best for the m88110, and may not run on them88100. 

I ndude an ident directive in the assembler output recording the source filename, compiler 
nameand version, timestamp, and compilation flags used. 

In assembler output, emit symbol names without adding an underscore character at the 
beginning of each name The default is to use an underscore as prefix on each name. 

Early models of the 88K architecture had problems with division by zero; in particular, many of 
them didn't trap. Use these options to avoid including (or to include explicitly) additional code 
to detect division by zero and signal an exception. All gcc configurationsfor the 88K use 
-mcheck-zero-division by default. 


-mocs-debug-info 

-mno-ocs-debug-info 


-mocs-frame-position 

-mno-ocs-frame-position 


Include (or omit) additional debugging information (about registers used in each stack frame) 
asspecified in the 880 pen 0 bject Compatibility Standard, OCS. This extra information is not 
needed by GD B. The default for DG/UX, SVr4, and Delta 88 SVr3.2 is to include this 
information; other 88K configurationsomitthisinformation by default. 

Force (or do not require) register values to be stored in a particular place in stack frames, as 
specified in OCS. TheDG/UX, Delta88 SVr3.2, and BCS configurations use-mocs-frame- 
position; other 88K configurationshavethedefault -mno-ocs- frame-position. 


-moptimize-arg-area C Ontrol hOW to Store function arguments i n Stack frames -moptimize-arg-area saves space but 

-mno-optimize-arg-area may break some debuggers (not G D B). -mno-optimize-arg-area conforms better to standards 
By default gcc does not optimize the argument area. 
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-mshort-data-niim 


-mserialize-volatile 
-mno-serialize-volatile 


-mtrap-large-shift 

-mhandle-large-shift 

-muse-div-instruction 

-mversion- 03.00 


-mwarn-passed-structs 


Generate smaller data references by making them relative to r 0 , which allows loading a value 
using a single instruction (rather than the usual two). You control which data references are 
affected by specifying num with thisoption. For example, if you specify -mshort-data-512, 
then the data references affected are those involving displacements of less than 512 bytes 
-mshort-data-num is not effective for n u m greater than 64K. 

D 0 , or do not, generate code to guarantee sequential consistency of volatile memory references. 
GNU CC always guarantees consistency by default, for the preferred processor submodel. How 
this is done depends on the submodel. 

T he m88100 processor does not reorder memory references and so always provides sequential 
consistency. Ifyou use-m 88 i 00 ,GNU CC does not generate any special instructionsfor 
sequential consistency. 

The order of memory references made by the m88110 processor does not always match the 
order of the instructions requesting those references. I n particular, a load instruction may 
execute before a preceding store instruction. Such reordering violates sequential consistency of 
volatile memory references, when there are multiple processors. W hen you use -11188000 or 
-m 88 i 10 , GNU CC generates special instructions when appropriate to force execution in the 
proper order. 

T he extra code generated to guarantee consistency may affect the performance of your 
application. If you know that you can safely forgo thisguarantee you may use the option 

-mno-serialize-volatile. 

Ifyou usethe-m 88 i 00 option but require sequential consistency when running on them88110 
processor, you should use -mserialize-volatile. 

T urn on (-msvr 4 ) or off (-msvr 3 ) compiler extensions related to System V release 4 (SVr4). This 
controls the following: 

Which variant of the assembler syntax to emit (which you can select independently using 
-mversion-03.00). 

-msvr 4 makestheC preprocessor recognize #pragma weak. 

-msvr 4 makes gcc issue additional declaration directives used in SVr4. 

-msvr 3 is the default for all m88K configurations except the SVr4 configuration. 

Include code to detect bit-shifts of more than 31 bits; respectively, trap such shifts or emit code 
to handle them properly. By default, gcc makes no special provision for large bit shifts. 

Very early models of the 88 K architecture didn't have a divide instruction, so gcc avoids that 
instruction by default. Use thisoption to specify that it'ssafeto usethedivide instruction. 

In theDG/UX configuration, there are two flavors of SVr4. Thisoption modifies -msvr 4 to 
select whether the hybrid-CO FF or real-ELF flavor is used. All other configurations ignore this 
option. 

Warn when a function passes a struct as an argument or result. Structure-passing conventions 
have changed during the evolution of theC language, and are often the source of portability 
problems By default, gcc issues no such warning. 


These options are defined for the IBM RS6000: 

-mf p-in-toc C ontrol whether or not floating-point constants go in the table of contents (TO C), a table of 

-mno-fp-in-toc all global variable and function addresses. By default gcc puts floating-point constants there; if 

theTOC overflows, -mno-fp-in-toc will reduce thesize of the TOC, which may avoid the 
overflow. 


These -m options are defined for the IBM RT PC: 


-min-line-mul 

-mcall-lib-mul 

-mfull-fp-blocks 


Use an inline code sequencefor integer multiplies. This isthe default. 

Call imui$$ for integer multiples. 

Generate full-size floating-point data blocks including the minimum amount of scratch space 
recommended by IBM . T his isthe default. 
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-mmimmum-fp-blocks 
-mfp-arg-in-fpregs 


-mfp-arg-in-gregs 

-mhc-struct-return 


-mnohc-struct-return 


D o not include extra scratch space in floating-point data blocks T his results in smaller code, 
but slower execution, since scratch space must be allocated dynamically. 

Use a calling sequence incompatible with thelBM calling convention in which floating-point 
arguments are passed in floating-point registers Notethatvarargs.hand stdargs.h will not 
work with floating-point operands if thisoption isspecified. 

Use the normal calling convention for floating-point arguments. This is the default. 

Return structures of more than one word in memory, rather than in a register. Thisprovides 
compatibility with theMetaWareHighC (he) compiler. Use-fpcc-struct-return for compat¬ 
ibility withthePortableC Compiler(PCC). 

Return some structures of more than one word in registers when convenient. This is the 
default. For compatibility with the IBM -supplied compilers use either -fpcc-struct-return or 

-mhc-struct-return. 


T hese -m options are defi ned for the M IP S family of computers: 




-mrnames, -mno-rnames 

-mgpopt, -mno-gpopt 

-mstats, -mno-stats 

-mmemepy, -mno-memepy 

-mmips-tfile 

-mno-mips-tfile 

-msoft-float 


Assume the defaults for the machinetypeepu- type when scheduling instructions The default 
epu-1 ype is default, which picks the longest cycles times for any of the machines in order that 
the code run at reasonable rates on all M IPS CPUs Other choices for c p u -1 y p e arer2 000, r300@, 
r4000,and r6000. While picking a specific c pu-1 y pe will schedule things appropriately for that 
particular chip, the compiler will not generate any code that does not meet level loftheM IPS 
ISA (instruction set architecture) with-outthe-mips2 or -mips 3 switches being used. 

Issue instructions from level 2 of the M IPS ISA (branch likely, square root instructions). 

The -mcpu=r 4000 or -mcpu=r6000 switch must be used in conjunction with -mips2. 

Issue instructions from level 3 of the M IPS ISA (64-bit instructions). The-mcpu=r 4000 switch 
must be used in conjunction with -mips2. 

T hese options don't work at present. 

Generate code for the M IPS assembler, and invoke mips-ttiie to add normal debug informa¬ 
tion. T his isthe default for all platforms except for the OSF/1 reference platform, using the 
0 SF/rose object format. If any of the -ggdb, -gstabs, or -gstabs+ switches are used, the mips- 
tfiie program will encapsulate the stabs within M IPS ECOFF. 

G enerate code for theGNU assembler. This isthe default on the 0 SF/1 reference platform, 
using the 0 SF/rose object format. 

The -mrnames switch saysto output code using the M IPS software names for the registers, 
instead of the hardware names (for example a0 instead of $4). TheGNU assembler does not 
support the -mrnames switch, and theM IPS assembler will be instructed to run theM IPSC 
preprocessor over the source file. The -mno-rnames switch isdefault. 

The -mgpopt switch saysto write all of the data declarations before the instructions in the text 
section, to all the M I PS assembler to generate one-word memory references i nstead of using 
two words for short global or static data items This is on by default if optimization is selected. 
For each noninlinefunction processed, the -mstats switch causes the compiler to emit one line 
to the standard error file to print statistics about the program (number of registers saved, stack 
size, and so on). 

The -mmemepy switch makes all block moves call the appropriate string function (memepy or 
bcopy) instead of possibly generating inline code. 

The -mno-mips-tfile switch causes the compiler to not post-process the object file with the 
mips-tfiie program, after the M I PS assembler has generated it to add debug support. If mips- 
tfiie isnot run, then no local variables will be avail able to the debugger. In addition, stage2 
and stage 3 objectswill have the temporary filenames passed to the assembler embedded in the 
object file which meanstheobjectswill not compare the same. 

Generate output containing library callsfor floating point. 
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WARNING 


The requisite librariesare not part ofGNU CC. Normally, thefacilitiesof themachinefs usual C compiler are used, but 
thiscan't bedonedirectly in cross-compilation. You must makeyour own arrangements to provide suitable library func¬ 
tions for cross-compilation. 


-mfp64 


-mfp32 

-mabicalls 

-mno-abicalls 

-mhalf-pic 


-nocpp 


Generate output containing floating point instructions This is the default if you use the 
unmodified sources. 

Assume that the fr bit in the status word is on, and that there are 32 64-bit floating-point 
registers, instead of 32 32-bit floating-point registers You must also specify the -mcpu=r40aa and 
-mips3 switches 

Assume that there are 32 32-bit floating-point registers. This isthe default. 

E mit (or do not emit) the. abicaiis,. cpioad, and . cprestore pseudo operations that some 
System V .4 ports use for position-independent code. 

The -mhalf-pic switch saysto put pointers to extern references into the data section and load 
them up, rather than put the references in the text section. This option does not work at 
present. 

Put global and static items less than or equal to num bytes into the small data or bss sections 
instead of the normal data or bss section. This allows the assembler to emit one-word memory 
reference instructions based on the global pointer (gp or $ 28 ), instead of the normal two words 
used. By default, num is 8 when theM I PS assembler is used, and owhen the GNU assembler is 
used. T he -Gnum switch is also passed to the assembler and linker. All modules should be 
compiled with the same -Gnum value. 

Tell theM I PS assembler to not run its preprocessor over user assembler files (with an .s suffix) 
when assembling them. 


T hese -m options are defined for the I ntel 80386 family of computers 

-m486, -mno-486 Control whether or notcodeisoptimizedfora486 instead of a 386. Codegenerated for a 486 

will run on a 386 and vice versa. 

-msoft-fioat Generate output containing library callsfor floating point. 


WARNING 


The requisite librariesare not part ofGNU CC. Normally, thefacilitiesof themachinefs usual C compiler are used, but 
thiscan't bedonedirectly in cross-compilation. You must makeyour own arrangements to provide suitable library func¬ 
tions for cross-compilation. 


On machines where a function returns floating point results in the 80387 register stack, some 
floating-point opcodes may be emitted even if -msoft-fioat is used. 

-mno-fp-ret-in-387 D o not use the FPU registers for return values of functions. 

The usual calling convention has functions return values of types float and double in an FPU 
register, a/en if there is no FPU. The idea is that the operating system should emulate an FPU. 
The option -mno-fp-ret-in-387 causes such values to be returned in ordinary CPU registers 
instead. 

T hese -m options are defi ned for the FI P PA fami ly of computers 
-mpa-risc-i -0 G enerate code for a PA 1.0 processor. 

-mpa-rise -1-1 Generatecodefor a PA 1.1 processor. 





-mkernel 

-mshared-libs 

-mno-shared-libs 
-mlong-calls 

-mdisable-fpregs 

-mdisable-indexing 

-mtrailing-colon 


Generate code which issuitablefor use in kernels Specifically, avoid add instructions in which 
oneof the arguments isthe DP register; generate addii instructions instead. This avoids a rather 
serious bug in the HP-UX linker. 

Generate code that can delinked against H P-UX shared libraries This option is not fully 
functioning yet, and is not on by default for any PA target. Using this option can cause 
incorrect code to be generated by the compiler. 

Don't generate code that will belinked against shared libraries. This is the default for all PA 
targets. 

Generate code which allows calls to functions greater than 256K away from the caller when the 
caller and callee are in the same source file. Do not turn this option on unless code refuses to 
link with branch out of range errors from the linker. 

Prevent floating-point registers from being used in any manner. This is necessary for compiling 
kernels that perform lazy context switching of floating-point registers. If you usethisoption 
and attempt to perform floating-point operations, the compiler will abort. 

Prevent the compiler from using indexing address modes. This avoids some rather obscure 
problems when compiling M IG -generated code under MACH. 

Add a colon to the end of label definitions (for ELF assemblers). 


T hese -m options are defi ned for the I ntel 80960 fami ly of computers 


-mnumerics 

-msoft-float 

-mleaf-procedures 

-mno-leaf-procedures 


-mcomplex-addr 

-mno-complex-addr 


-mno-code-align 


-mintel-asm 


-mstrict-align 

-mno-strict-align 

-mold-align 


Assume the defaultsfor the machinetype c pu-1 ype for instruction and addressing-mode 
availability and alignment. The default c pu-type is kb; other choices are ka, me, ca, cf, sa, and sb. 
The -mnumerics option indicates that the processor does support floating-point instructions 
The -msoft-fioat option indicates that floating-point support should not be assumed. 

Do (or do not) attempt to alter leaf procedures to be callable with thebai instruction as well as 
cal i. This will result in more efficient code for explicit calls when thebai instruction can be 
substituted by the assembler or linker, but less efficient code in other cases such as calls via 
function pointers, or using a linker that doesn't support this optimization. 

Do (or do not) make additional attempts (beyond those of the machine-independent portions 
of the compiler) to optimize tail-recursive calls into branches. You may not want to do this 
because the detection of cases where this is not valid is not totally complete. The default is 
-mno-tail-call. 

Assume (or do not assume) that the use of a complex addressing mode is a wi n on this imple¬ 
mentation of the i960. Complex addressing modes may not be worthwhile on the K-series, but 
they definitely are on theC-series. The default iscurrently -mcompiex-addr for all processors 
except the CB and CC. 

Align code to 8-byte boundariesforfasterfetchingfor don't bother). Currently turned on by 
default for C-series implementations only. 

Enable compatibility with iC 960 v2.0orv3.0. 


E nable compatibility with the iC 960 assembler. 

D o not permit (do permit) unaligned accesses. 

Enable structure-alignment compatibility with Intel'sgcc release version 1.3 (based on gcc 
1.37). Currently this is buggy in that #pragma align i isalways assumed as well, and cannot be 
turned off. 
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These -m options are defined for the DEC Alpha implementations: 


-mno-soft-float 
-msoft-float 


-mfp-reg, -mno-fp-regs 


Usefdo not use) the hardware floating-point instructions for floating-point operations When 
-msoft-float isspecified, functionsin libgcci .c will be used to perform floating-point 
operations. U nless they are replaced by routines that emulate thefloating-point operations or 
compiled in such away as to call such emulations routines these routines will issuefloating- 
point operations If you are compiling for an Alpha without floating-point operations you 
must ensure that the library is built so as not to call them. 

N otethat Alpha implementations without floating-point operations are required to have 
floating-point registers. 

Generate code that uses (does not use) thefloating-point register set. -mno-fp-regs implies 
-msoft-float. If thefloating-point register set is not used, floating-point operands are passed in 
integer registers as if they were integers and floating-point results are passed in $0 instead of $fo. 
This is a nonstandard calling sequence so any function with a floating-point argument or 
return value called by codecompiled with -mno-fp-regs must also be compiled with that 
option. 

A typical use of this option is building a kernel that does not use, and hence need not save and 
restore, any floating-point registers 


These additional options are available on System V Release 4 for compatibility with other compilers on those systems 
-g 0 n SV r4 systems, gcc accepts the option -g (and passes it to the system linker), for compatibil¬ 

ity with other compilers H owever, we suggest you use-symbolic or -shared as appropriate 
instead of supplying linker options on the gcc command line 

-Qy Identify the versions of each tool used by the compiler, in an .idem assembler directive in the 

output. 

-Qn Refrain from adding .idem directives to theoutput file (this is the default). 

-yp.di r s Search the directories d i r s, and no others, for libraries specified with -1. You can separate 

directory entriesin di r s from one another with colons. 

-Ym.di r Look in the directory di r to find theM 4 preprocessor. The assembler usesthisoption. 


CODEGENERATION OPTIONS 


These machine-independent options control the interface conventions used in codegeneration. 


M ostof them begin with -f. These options have both positive and negative forms; the negative form of-ffoo would be-fno- 
foo. In thefollowing table, only one of theformsislisted-theonewhich is not the default. You can figure out theother 
form by either removing no- or adding it. 


-fnonnull-objects 


-fpcc-struct-return 


-freg-struct-return 


Assume that objects reached through references are not null (C++ only). 

N ormally, GNU C ++makes conservative assumptions about objects reached through 
references. For example, the compiler must check that a is not null in code like thefollowing: 
obj &a = g (); a.f (2); 

Checking that references of this sort have nonnull values requires extra code however, and it is 
unnecessary for many programs. You can use -fnonnuii-objects to omit thechecksfor null, if 
your program doesn't require checking. 

Use the same convention for returning struct and union values that is used by the usual C 
compiler on your system. This convention is less efficient for small structures, and on many 
machines it failsto be reentrant; but it has the advantage of allowing intercallability between 
gee-compiled code and pcc-compiled code 

Use the convention that struct and union values are returned in registers when possible This is 
more efficient for small structures than -fpcc-struct-return. 

If you specify neither -fpcc-struct-return nor -freg-struct-return, GN U CC defaults to 
whichever convention is standard for the target. If there is no standard convention, G N U CC 
defaults to -fpcc-struct-return. 
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-fshort-double 


Allocate to an enum type only as many bytes as it needs for the declared range of possible values 
Specifically, the enum type will be equivalent to the smallest integer type that has enough room. 
Use the same size for double asfor float. 


-f shared-data Requests that the data and non-const variables of this compilation be shared data rather than 

private data. The distinction makes sense only on certain operating systems, where shared data 
is shared between processes running the same program, while private data exists in one copy per 


-fno-common 


-finhibit-size-directive 


-fverbose-asm 


-fvolatile 
-fvolatile-global 
-f pic 


-fPIC 

-ffixed-reg 


-fcall-saved-reg 


Allocate even uninitialized global variables in thebss section of the object file rather than 
generating them as common blocks. This has the effect that if the same variable is declared 
(without extern) in two different compilations, you will get an error when you link them. The 
only reason this might be useful is if you want to verify that the program will work on other 
systems which always work this way. 

Ignore the #ident directive. 

Do not output global initializations (such as C++constructors and destructors) in theform 
used by theGN U linker (on systems wheretheG N U linker isthe standard method of handling 
them). Use this option when you want to useanon-GN U linker, which also requires using the 
coiiect 2 program to make sure the system linker includes constructors and destructors 
(coiiect 2 isincluded intheGNU CC distribution.) For systems that must use coiiect 2 , the 
compiler driver gcc isconfigured to do this automatically. 

Don't output a .size assembler directive or anything else that would cause trouble if the 
function issplit in the middle, and the two halves are placed at locations far apart in memory. 
This option is used when compiling crtstuff.c; you should not need to use it for anything else 
Put extra commentary information in the generated assembly code to make it more readable. 
This option is generally only of use to those who actually neol to read the generated assembly 
code (perhaps while debugging the compiler itself). 

Consider all memory references through pointers to be volatile. 

Consider all memory references to extern and global data items to be volatile. 

If supported for the target machines, generate position-independent code, suitable for use in a 
shared library. 

If supported for the target machine, emit position-independent code suitable for dynamic 
linking, even if branches need large displacements 

Treat the register named r eg as a fixed register; generated code should never refer to it (except 

perhaps as a stack pointer, frame pointer, or in some other fixed role). 

reg must be the name of a register. The register names accepted are machine-specific and are 

defined in the register_names macro in the machine description macro file 

Thisflag does not have a negative form, because it specifies a three-way choice 

Treat the register named reg as an allocable register that is clobbered by function calls. It may 

be allocated for temporaries or variables that do not live across a call. Functions compiled this 

way will not save and restore the register reg. 

U se of thisflag for a register that has a fixed pervasive role in the machine's execution model, 
such as the stack pointer or frame pointer, will produce disastrous results 
Thisflag does not have a negative form, because it specifies a three-way choice 
T reat the register named reg as an allocable register saved by functions It may be allocated even 
for temporariesor variables that live acrossa call. Functionscompiled thisway will save and 
restore the register reg if they use it. 

U se of thisflag for a register that has a fixed pervasive role in the machine's execution model, 
such as the stack pointer or frame pointer, will produce disastrous results 
A different sort of disaster will result from the use of thisflag for a register in which function 
values may be returned. 

Thisflag does not have a negative form, because it specifies a three-way choice 
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PRAGMAS 


Two #pragmadiredivesaresupportedforGNU C++to permit using the same header file for two purposes: as a definition of 
interfaces to a given object class, and as the full definition of the contents of that object cl ass 


#pragma interface 


#pragma implementation 
#pragma implementation 
"obj ects .h" 


(C++only.) Usethisdirective in header files that define object classes, to save space in most of 
the object files that use those classes Normally, local copies of certain information (backup 
copies of inline member functions debugging information, and the internal tables that 
implement virtual functions) must be kept in each object file that includes class definitions. You 
can use this pragma to avoid such duplication. W hen a header file containing #pragma 
interface is included in acompilation, thisauxiliary information will not be generated (unless 
the main input source file itself uses#pragma implementation). Instead, the object files will 
contain references to be resolved at link time. 

(C++only.) Use this pragmain amain input file, when you wantfull output from included 
header files to be generated (and made globally visible). The included header file, in turn, 
should use#pragma interface. Backup copies of inline member functions debugging informa¬ 
tion, and the internal tables used to implement virtual functions are all generated in implemen¬ 
tation files. 

If you use#pragma implementation with no argument, it applies to an include file with the same 

basename as your source file; for example, in aiiciass.cc, #pragma implementation by itself is 

equivalent to #pragma i-piementation "aiiciass.h". Use the string argument if you want a 

single implementation file to include code from multiple header files 

There is no way to split up the contents of a single header file into multiple implementation 

files 


FILES 

file.c 

file.h 

file.i 

file.C 

file.cc 

file.cxx 

file.m 

file.s 

file.o 

TMPDI R/cc 
LI BDI R/cpp 
LI BDI R/ccI 
LI BDI R/ccIplus 
LI BDI R/collect 
LI BDI R/libgcc.a 
/lib/crt[01n ].0 
LI BDI R/ccrt0 
/lib/libc.a 
/usr/include 
LI BDI R/include 
LI BDI R/g++-include 


C source file 

C header (preprocessor) file 
Preprocessed C source file 
C++source file 
C++source file 
C++source file 
Objective-C source file 
Assembly language file 
Object file 
Link edited output 
Temporary files 
Preprocessor 
Compiler for C 
Compiler for C++ 

Linker front end needed on some machines 
gcc subroutine library 
Startup routine 

Additional startup routinefor C ++ 
Standard C library; see intro(3) 

Standard directory for #inciude files 
Standard gcc directory for #inciude files 
Additional g++directory for #inciude 


LI BDI R is usually /usr/local/lib/machi ne/*ersi on. 

tmpdi r comes from the environment variable tmpdir (default /usr/tmp if available; otherwise, / tmp.). 
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SEE ALSO 

cpp(l), as(l), ld(l), gdb(l), adb(l), dbx(l), sdb(l) 
gcc, cpp, as, Id, and gdb entries in info. 

U 3 ng and Porting GNU CC (for version 2.0), Richard M . Stallman; The C Preprocessor, Richard M . Stallman; Debugging 
with GDB: theGNU Source-Ls/d Debugger, Richard M . Stallman and Roland H. Pesch; Usngas theGNU Assembler, Dean 
Eisner, Jay Fenlason & friends; Id: theGNU Linker, Steve Chamberlain and Roland Pesch. 

BUGS 

For instructions on reporting bugs, see the GCC manual. 

COPYING 

Copyright 1991,1992,1993 Free Software Foundation, Inc. 

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this 
permission notice are preserved on all copies. 

Permission isgranted to copy and distribute modified versions of this manual under the conditionsfor verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to thisone. 
Permission isgranted to copy and distribute translations of this manual into another language under the preceding 
conditionsfor modified versions, except that this permission notice may be included in translations approved by the Free 
Software Foundation instead of in theoriginal English. 

AUTHORS 

SeetheGNU CC manual for the contributors to GNU CC. 

GNU Tools 13 October 1993 


gemtopbm 

gemtopbm — Convert a GEM IMG file into a portable bitmap 

SYNOPSIS 

gemtopbm [-d] I gemfile ] 

DESCRIPTION 

ReadsaGEM IMG fileasinput. Readsfrom stdin if input file isomitted. Produces a portable bitmap as output. 

OPTIONS 

■d Produceoutput describing the contents of the IM G file. 

BUGS 

D oes not support files containing more than one plane. 

SEE ALSO 

pbmtogem(l), pbm(5) 

AUTHOR 

Copyright© 1988 DiomidisD. Spinellis (dds@cc.ic.ac.uk). 


11 July 1992 
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geqn 

geqn— Format equationsfor troff 

SYNOPSIS 

geqn [ -rvCNR ][-dcc ] [-Tname ][-Mdir ] [-f F ][-sn ][-pn ] [-mn ] [files ... ] 

DESCRIPTION 

This manual page describes the GN U version of eqn, which ispartofthegroff document formatting system, eqn compiles 
descriptions of equations embedded within troff input files into commands that are understood by troff. N ormally, it 
should be invoked using the -e option of groff. The syntax is quite compatible with UN IX eqn. The output of GN U eqn 
cannot be processed with UN IX troff; it must be processed with GNU troff. If no files are given on the command line the 
standard input will be read. A filename of - will cause the standard input to be read. 

eqn searches for the file eqnrc using the path .:/usr/iib/groff/tmac:/usr/iib/tmac. If it exists, eqn will process it before the 
other input files. The -r option prevents this. 

GNU eqn does not provide the functionality of neqn: it does not support low-resolution, typewriter-like devices (although it 
may work adequately for very simple input). 

OPTIONS 

-c Recognize .eq and .en even when followed by acharacter otherthan spaceor newline. 

-n Don't allow newlines within delimiters. This option allows eqn to recover better from missing closing 

delimiters. 

-v Print the version number. 

-r Only one size reduction. 

-mn Theminimum point-size is n. eqn will not reducethesizeof subscriptsor superscripts to asmaller size 

than n. 

-Tname The output is for de/ice name. The only effect of this isto define a macro name with a value of i. Typically, 

eqnrc will usethisto provide definitions appropriate for the output device. The default output deviceisps. 
-Mdi r Search di r for eqnrc before the default directories 

-R Don't load eqnrc. 

-tf T his is equivalent to a gfontF command. 

-sn This is equivalent to agsizen command. Thisoption isdeprecated. eqn will normally set equations at 

whatever the current pointsize is when the equation is encountered. 

-pn This says that subscripts and superscripts should ben points smaller than the surrounding text. Thisoption 

isdeprecated. N ormally, eqn makes sets subscripts and superscripts at 70 percent of the size of the 
surrounding text. 

USAGE 

Only the differences between GNU eqn and UN IX eqn are described here 

M ost of the new features of G N U eqn are based on T eX. T here are some references to the differences between T eX and 
GNU eqn asfollows; these may safely be ignored if you do not know TeX. 

AUTOMATIC SPACING 

eqn gives each component of an equation a type, and adjusts the spacing between components using that type. Possible types 
are 

ordinary An ordinary character such as i or x 

operator A I arge operator such as; 

binary A binary operator such as + 

relation A relation such as = 
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opening An opening bracket such as ( 

closing A dosing bracket such as) 

punctuation A punctuation character such as, 

inner A subformula contained within brackets 

suppress Spacing that suppresses automatic spacing adjustment 

Components of an equation get a type in one of two ways: 

typete This yieldsan equation component that containse but that has type t, where t is one of the types 

mentioned previously. For example, times isdefined as 


The name of the type doesn't have to be quoted, but quoting protects from macro expansion, 
chartypet text Unquoted groupsof charactersaresplitup into individual characters, and the type of each character is 
looked up; this changes the type that is stored for each character; it says that the characters in text from 
now on havetypet. For example 


would make the characters .,;: have type punctuation whenever they subsequently appeared in an 
equation. The type t can also be letter or digit; in these cases, chartype changes the font type of the 
characters. Seethe"Fonts" section, later in thismanual page. 


NEW PRIMITIVES 

elsmallovere2 



splittext 



This is similar to over; smaiiover reduces the size of ei and e 2 ; it also puts less vertical space between e 1 or 
e2 and thefraction bar. Theover primitive corresponds to the\over primitive in display styles; smaiiover 
corresponds to \over in nondisplay styles 

T his vertically centers e about the math axis The math axis is the vertical position about which characters 
such as+ and - are centered; also it is the vertical position used for the bar of fractions. For example, sum is 
defined as 

{type "operator" vcenter size 45 \(*S} 

T his sets e 2 as an accent over e i . e 2 is assumed to be at the correct height for a lowercase letter; e 2 will be 
moved down according if e 1 istaller or shorter than a lowercase letter. For example, hat isdefined as 
accent } 

dotdot, dot, tilde, vec, and dyad arealso defined using the accent primitive 
Thissets e 2 as an accent under e 1 . e 2 isassumed to be at the correct height for a character without a 
descender; e 2 will be moved down if e 1 has a descender, utiide is predefined using uaccent as a tilde accent 
below the baseline 

This has thesame effect as simply text, but text is not subject to macro expansion because it is quoted; 
text will be split up and the spacing between individual characters will be adjusted. 

This has the same effect as text, but because text is not quoted it will be subject to macro expansion; text 
will not be split up and the spacing between individual characters will not be adjusted. 

This is a variant of prime that acts as an operatorone.lt produces a different result from prime in a case 
such asAopprimesubi : With opprime the i will be tucked under the prime asasubscript to the a {as is 
conventional in mathematical typesetting), whereas with prime the i will be a subscript to the prime 
character. The precedence of opprime isthe same as that of bar and under, which is higher than that of 
everything except accent and uaccent. In unquoted text, a ■ that is not the first character will be treated 
like opprime. 

This constructs a new object frame using a gtroff (1) macro named text . When the macro is called, the 
string os will contain the output for e, and the number registers ow, eh, 0 d, 0 skern and oskew will contain 
the width, height, depth, subscript kern, and skew of e. (Thesubscript kern of an object says how much a 
subscript on that object should be tucked in; the*ew of an object says how far to the right of the center of 
the object an accent over the object should be placed.) The macro must modify 0s so that it will output 
the desired result with itsorigin atthecurrent point, and increase the current horizontal position by the 
width of the object. T he number registers must also be modified so that they correspond to the result. 
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For example, suppose you wanted a construct that cancels an expression by drawing a diagonal line through it: 

■ EQ 

define cancel 'special Ca 1 

.EN 

.de Ca 

.ds 0s \Z'\\*(0s 1 \v'\\n(0du 1 \D'1 \\n(0wu -\\n(0hu-\\n(0du'\v'\\n(0hu' 

Then you could cancel an expression U with cancel e. 

H ere's a more complicated construct that draws a box around an expression: 

■ EQ 

define box 'special Bx' 


.de Bx 

.ds 0s \Z'\h'1n'\\*(0s'\ 

\Z'\v'\\n(0du+1n'\D'l \\n(0wu+2n 0'\D'1 0 -\\n(0hu-\\n(0du-2n'\ 
\D'1 -\\n(0wu-2n 0'\D'1 0 \\n(0hu+\\n(0du+2n"\h'\\n(0wu+2n' 


CUSTOMIZATION 

The appearance of equations iscontrolled by a large number of parameters These can be set using the set command, 
setpn This sets parameter p tovaluenjn isan integer. For example 

set x_height 45 

says that eqn should assume an x height of 0.45 ems. 


Possible parameters are as follows. V aluesare in units of hundredths of an em unless otherwise stated. T hese descriptions are 
intended to be expository rather than definitive 


delimiter_factor 


delimiter_shortfall 


null_delimiter_space 

script_space 

thin_space 

medium_space 

thick_space 


eqn will not set anything at a smaller point size than this The value is in points. 

Thefat primitive emboldens an equation by overprinting two copies of the equation horizontally 
offset by this amount. 

A fraction bar will be longer by twice this amount than the maximum of the widths of the 
numerator and denominator; in other words, it will overhang the numerator and denominator by 
at least this amount. 

When bar or under isapplied to a single character, the line will be this long. Normally, bar or 
under produces a line whose length is the width oftheobjectto which it applies; in thecaseof a 
single character, thistendsto producea line that looks too long. 

Extensible delimiters produced with the left and right primitives will have a combined height and 
depth of at least this many thousandths of twice the maximum amount by which the subequation 
that the delimiters enclose extends away from the axis. 

Extensible delimiters produced with the left and right primitives will have a combined height and 
depth not less than the difference of twice the maxi mum amount by which the subequation that 
the delimiters enclose extends away from the axis and thisamount. 

This much horizontal space is inserted on each side of a fraction. 

The width of subscripts and superscripts is increased by thisamount. 

Thisamount of space ^automatically inserted after punctuation characters. 

Thisamount of space is automatically inserted on either side of binary operators. 

Thisamount of space is automatically inserted on either side of relations 
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xjieight The height of lowercase letters without ascenders such asx. 

axis_height The height above the baseline of the center of characters such as+and It is important that this 

value be correct for the font you are using. 

def auit_ruie_thickness This should set to the thickness of the \ ( ru character, or the thickness of horizontal lines produced 
withthe\D escape sequence. 

numi The over command will shift up the numerator by at least this amount. 

num 2 The smaiiover command will shift up the numerator by at least this amount, 

denomi T he over command will shift down the denominator by at least this amount. 

denom 2 The smaiiover command will shift down the denominator by at least this amount, 

supi Normally superscripts will be shifted up by at least this amount. 

sup 2 Superscripts within superscripts or upper limitsor numeratorsof smaiiover fractions will be shifted 

up by at least this amount. This is usually less than supi. 

sup3 Superscripts within denominators or square roots or subscripts or lower limitswill beshifted up by 

at least this amount. This is usually less than sup 2 . 
subi Subscripts will normally beshifted down by at least this amount. 

sub 2 When there is both a subscript and a superscript, the subscript will beshifted down by at least this 

amount. 

sup_drop The baseline of a superscript will be no more than this amount below the top of the object on 

which the superscript is set. 

sub_drop The baselineof a subscript will beat least this much below the bottom of the object on which the 

subscript is set. 

big_op_spacingi T he baseli neofan upper limit will be at least this much abovethetop of the object on which the 

limit isset. 

big_op_spacing 2 The baselineof a lower limit will beat least this much below the bottom of the object on which the 

limit isset. 

big_op_spacing3 The bottom of an upper limit will beat least this much abovethetop of the object on which the 

limit isset. 

big_op_spacing4 The top of a lower limit will beat least this much below the bottom of the object on which the 

limit isset. 

big_op_spacing5 Thismuch vertical space will be added aboveand below limits. 

baseiine_sep Thebaselinesof the rows in a pile or matrix will normally be thisfar apart. In most cases, this 

should be equal to the sum of numi and denomi. 

shitt_down The midpoint between the top baseline and the bottom baseline in a matrix or pile will beshifted 

down by this much from the axis In most cases, this should be equal to axisjeight. 
coiumnjsep Thismuch space will be added between columns in a matrix. 

matrix_side_sep Thismuch space will be added at each side of a matrix. 

draw_iines If this is nonzero, lines will be drawn using the \d escape sequence rather than with the \i escape 

sequence and the \ ( ru character. 

body_height T he amount by which the height of the equation exceeds this will be added as extra space before 

the line containing the equation (using \x.) The default value is 85. 
body_depth The amount by which the depth of theequation exceeds this will beadded as extra space after the 

linecontaining the equation (using \x.) The default value is35. 
nroff If this is nonzero, then ndefine will behave like define and tdefine will be ignored; otherwise, 

tdefine will behave like define and ndefine will be ignored. T he default value is 0 . (This is typically 
changed to i by theeqnrc file for the ascii and latim devices) 

A more precise description of the role of many of these parameters can be found in Appendix H of T he T eXbook. 
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MACROS 

M acroscan take arguments In a macro body, $ n where n is between 1 and 9, will be replaced by the nth argument if the 
macro is called with arguments if there are fewer than n arguments, it will be replaced by nothing. A word containing a left 
parenthesis where the part of the word before the left parenthesis has been defined using thedefine command will be 
recognized as a macro call with arguments characters following the left parenthesis up to a matching right parenthesis will be 
treated as comma-separated arguments; commas inside nested parentheses do not terminate an argument, 
sdefinenamexanyt hi ngx Thisis like the define command, but name will not be recognized if called with arguments 
inciudef i i e I ndude the contents of f i i e . Linesof f i e beginning with . eq or .en will be ignored, 

ifdetnamexanyt hi ngx If name has been defined by define (or has been automatically defined because name istheoutput 
device), process anyt hi ng ; otherwise ignore a nyt hi ng. 
x can be any character not appearing in anythi ng. 


FONTS 

eqn normally uses at least two fonts to set an equation: an italic font for letters and a Roman font for everything else The 
existing gfont command changes the font that is used as the italic font. By default this is i. The font that is used as the 
Roman font can be changed by using the new grf ont command, 
grfontf Set the Roman font to f . 

T he italic primitive uses the current italic font set by gfont; the Roman primitive uses the current Roman font set by grf ont. 
There is also a new gbfont command, which changes thefont used by the bold primitive. If you only use the Roman, italic, 
and bold primitives to change fonts within an equation, you can change all the fonts used by your equations just by using 
gfont, grfont, and gbfont commands 

You can control which characters are treated as letters (and therefore set in italic) by using the chartype command described 
earlier. A type of letter will cause a character to be set in italic type. A type of digit will cause a character to besdt in Roman 
type. 

FILES 

/usr/lib/groff/tmac/eqnrc Initialization file 

BUGS 

Inline equations will be set at the pointsize that is current at the beginning of the input line. 

SEE ALSO 

groff(l), gtroff(l), groff_font(5), TZieTeYbOOk 

getlist 

getlist-Gdt a list from an N NTP server 

SYNOPSIS 

getlist [ -h host ][IiSt [ pattern [ types ]]] 

DESCRIPTION 

The getlist program obtains a list from an N NTP server and sends it to standard output. 

T he list may be one of active, active .times, distributions, Or newsgroups. T hese Values request the active(5), 
active.times, /news/lib/distributions, Or /news/lib/newsgroups files, respectively. 

If the-h flag is used, then the program connects to the server on the specified host. The default is to connect to the server 
specified in the inn.conf(5) file 



getopt 


FI 


If the i i st parameter is active, then the pattern and types parameters may be used to limit the output. When pattern is 
used, only active lines with groups that match according to wiidmat(3) are printed. When types is also given, only active lines 
that haveafourth field starting with a character found intypes are printed. 

For example, the following command will obtain the one-line descriptions of all newsgroups found on uunet: 

getlist -h news.uu.net newsgroups 

Thefollowing line lists all groups where local postings are permitted, moderated, or aliased: 

getlist active ym= 

Note that the listing files other than the activefileisa common extension to the N N TP protocol and may not be available 
on all servers 

HISTORY 

Written by Landon Curt Noll (<chongo@toad.com>) for InterNdtNews 

SEE ALSO 

active(5), nnrpd(8), wildmat(3) 

getopt 

getopt- Parse command options 

SYNOPSIS 

set - 'getopt optstring $*' 

DESCRIPTION 

getopt is used to break up options in command lines for easy parsing by shell procedures and to check for legal options 
optstring isa string of recognized option letters; see getopt(3). If a letter is followed by a colon, the option isexpected to 
have an argument that may or may not be separated from it by whitespace The special option -- is used to delimit the end 
of the options, getopt will place - - in the arguments at the end of the options, or recognize it if used explicitly. The shell 
arguments ($1 $2 ...) are reset so that each option is preceded by a - and in its own shel I argument; each option argument 
is also in its own shell argument. 

EXAMPLE 

Thefollowing codefragment shows how one might process the arguments for a command that can take the options a and b, 
and the option 0, which requires an argument: 
set — 'getopt abo: $*' 

if test $? != 0 

echo 'Usage: ...' 
exit 2 

for i 


-a|-b) 


flag=$i; shift;; 
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This code will accept any of the following as equivalent: 

cmd -aoarg file file 
cmd -a -o arg file file 
cmd -oarg -a file file 
cmd -a -oarg -■ file file 


SEE ALSO 

sh(l), getopt(3) 

DIAGNOSTICS 

getopt prints an error message on the standard error output when it encounters an option letter not included in optstring. 

HISTORY 

Written by H enry Spencer, working from a Bell Labs manual page. Behavior believed identical to the Bell version. 

BUGS 

Whatever getopt(3) has 

Arguments containing whitespace or embedded shell meta characters generally will not survive intact; this looks easy to fix 
but isn't. 

Theerror message for an invalid option is identified as coming from getopt rather than from the shell procedure containing 
the invocation of getopt; this, again, is hard to fix. 

The precise best way to use the set command to set the arguments without disrupting the value(s) of shell options varies 
from one shell version to another. 

21Junel993 


giftopnm 

giftopnm— Convert a GIF file into a portable anymap 

SYNOPSIS 

giftopnm [-verbose][-comments][-image N ] [GlFfiIe ] 

DESCRIPTION 

Reads a GIF file for input, and outputs portable anymap. 

OPTIONS 

-verbose Produces verbose output about the GIF fileinput. 

-comments 0 nly outputs GIF89 comment fields. 

-image 0 utputs the specified GIF image from theinput GIF archive (where n is i, 2 , 20 . ..). N ormally, there is 

only one image per file, so thisoption is not needed. 

All flags can be abbreviated to their shortest unique prefix. 

BUGS 

This does not correctly handle the Plain T ext Extension of the GIF89 standard, since I did not have any example input files 
containing them. 
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SEE ALSO 

ppmtogif(1), ppm(5) 

AUTHOR 

Copyright © 1993 by David Koblas(kobias@netcom.com) 

29 September 1993 


gindxbib 

gindxbib- M ake inverted index for bibliographic databases 

SYNOPSIS 

gindxbib [ -vw] [-c file] [-d dir] [-f file] [-h n] [-1 string] 

[-k n] [-1 n] [-n n] [-0 file] [-t n] [filename ...] 

DESCRIPTION 

gindxbib makes an inverted index for the bibliographic databasesin f i i ename ... for use with grefer(l), giookbib(l), and 
lkbib(l). The index will be named fi i ename .i; the index is written to a temporary file which isthen renamed to this If no 
filenames are given on the command line because the -f option has been used, and no-o option isgiven, the index will be 
named ind.i. 

Bibliographic databases are divided into records by blank lines. W ithin a record, each fields starts with a % character at the 
beginning of a line. Fields have a one-letter name that follows the% character. 

T he values set by the -c, -n, -1, and -t options are stored in the index; when the index is searched, keys will be discarded and 
truncated in a manner appropriate to these options; the original keys will be used for verifying that any record found using 
the index actually contains the keys. This means that a user of an index need not know whether these options were used in 
the creation of the index, provided that not all the keys to be searched for would have been discarded during indexing and 
that the user supplies at least the part of each key that would have remained after being truncated during indexing. The value 
set by the -i option is also stored in the index and will be used in verifying records found using the index. 

OPTIONS 

-v Print the version number. 

-w Index whole files Each file is a separate record. 

-cfiie Readthelistofcommonwordsfromme instead of /usr/iib/groff/eign. 

-ddi r Used r as the pathname of the current working directory to store in the index, instead of the path printed 

by pwd(l). Usually di r will be a symbolic link that points to the directory printed by pwd(l). 

-ff i 1 e Read the files to be indexed from file. If ff/e is -, files will be read from the standard input. The-f option 

can be given at most once 

-1st ring Don't index the contents of fields whose names are in s t r i ng . Initially, string isxYz. 

-hn U se the first primegreater than or equal to n for the size of the hash table Larger values of n will usually 

make searching faster, but will make the index larger and gindxbib use more memory. Initially, n is 997 . 

-kn U se at most n keys per input record. I nitially, n is 100. 

-in Discard keysthat are shorter than n. Initially, n is 3 . 

-nn D iscard the n most common words I nitially, n is 100. 

-obas ename The index should be named basename .i. 

-tn T runcate keys to n . Initially, n is6. 
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FILES 

Ind.i 

/usr/lib/groff/eign 

indxbibXXXXXX 


Index 

Default index name 
List of common words 
Temporary file 


SEE ALSO 

grefer(l), lkbib(l), glookbib(l) 


Groff Verson 1.09,16 April 1993 


glookbib 

giookbib— Search bibliographic databases 

SYNOPSIS 

glookbib [ -v ][-is t r i n g J[-tn ] filename ... 

DESCRIPTION 

glookbib prints a prompt on the standard error (unless the standard input is not a terminal), readsfrom the standard input a 
linecontaining a set of keywords, searches the bibliographic databasesf i ename ... for references containing those keywords, 
prints any references found on the standard output, and repeats this process until the end of input. For each database 
n i ename to be searched, if an index fi i ename.i created by gindxbib(l) exists, then it will be searched instead; each index can 
cover multiple databases. 

OPTIONS 

-v Print the version number. 

-istri ng When searching files for which no index exists, ignore the contents of fields whose names are in str i ng. 

-tn Only require the first n characters of keys to begiven. Initially, n is6. 

FILE 

filename.! Index files 

SEE ALSO 

grefer(l), lkbib(l), gindxbib(l) 

gnroff 

gnroff— Emulate nroff command with groff 

SYNOPSIS 

gnroff [ -h ][-i ][-mname ] [-nnum ] [-ol i s t ][-rcn ] [ -Tn a me ] [f i I e . . . ] 

DESCRIPTION 

The gnroff script emulates the nroff command using groff. The-T option with an argument other than ascii and latirn 
will beignored. The-h option is equivalent to thegrotty -h option. The-i, -n, -m, -o, and -r options have the effect 
described in gtroff(l). In addition, gnroff silently ignores options of -e, -q, or -s. 




SEE ALSO 

groff(l), gtroff(l), grotty(l) 



GroffVeraon 1.09,17 May 1993 


gouldtoppm 

gouidtoppm— Convert Gould scanner file into a portable pixmap 

SYNOPSIS 

gouldtoppm[gouI dfiI e ] 

DESCRIPTION 

Reads a file produced by the G ould scanner as input. Produces a portable pixmap as output. 

SEE ALSO 

PPm( 5 ) 

AUTHOR 

Copyright© 1990 by Stephen Paul Lesniewski 

20 May 1990 


gpic 

gpic— Compile pictures for troff orTeX 

SYNOPSIS 

gpic [ -nvC ][f i I ename ... ] gpic -t [ -cvzC ][fiIe n a me ... ] 

DESCRIPTION 

This manual page describes the GN U version of pic, which ispartofthegroff document formatting system, pic compiles 
descriptions of pictures embedded within troff orTeX input files into commands that are understood byTeX or troff. 

Each picture starts with a line beginning with .ps and ends with a line beginning with .pe. Anything outside of .ps and .pe 
is passed through without change. 

It isthe user's responsibility to provide appropriate definitions of the ps and pe macros. When the macro package being used 
does not supply such definitions (for example old versions of -ms), appropriate definitions can be obtained with -mpic: These 
will center each picture. 

OPTIONS 

Options that do not take arguments may be grouped behind a single-. The special option - can be used to mark the end of 
the options A filename of - refers to the standard input. 

-c Recognize .ps and .pe even when followed by acharacter otherthan spaceor newline. 

-n Don't usethegroff extensions to the troff drawing commands You should use this if you are using a 

postprocessor that doesn't support these extensions T he extensions are described in groff_out(5). T he -n option 
also causes pic not to use zero-length lines to draw dots in troff mode 
-t TeX mode. 

-c Be more compatible with tpic. Implies-t. Lines beginning with n are not passed through transparently. Lines 
beginning with . are passed through with the initial . changed to \. A line beginning with .ps isgiven special 
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treatment: Ittakesan optional integer argument specifying the line thickness (pen size) in milli-inches; a missing 
argument restores the previous line thickness; the default line thickness is8 milli-inches. The line thickness thus 
specified takes effect only when a nonnegative line thickness has not been specified by use of thethickness 
attribute or by setting the linethick variable 
-v Print the version number. 

-z InTeX mode draw dots using zero-length lines 
Thefollowingoptionssupported by other versions of pic are ignored: 

-d Draw all lines using the \d escape sequence, pic always does this 

-Tdev Generate output for the tr-off devicedev. This is unnecessary because the troff output generated by pic isdevice- 
independent. 


USAGE 

This section describes only the differences between GNU pic and the original version of pic. M any of these differences also 
apply to newer versions of UNIX pic. 


mode isenabled by the -t option. In mode, pic will define a vbox called ngraph for each picture. You must yourself print that 
vbox using, for example, the command: 

\centerline{\box\graph} 

Actually, since the vbox has a height of zero, this will produce slightly more vertical space above the picture than below it, the 
line 

\centerline{\raise 1em\box\graph} 

would avoid this 

You must use a driver that supports the tpic specials, version 2. 

Lines beginning with \are passed through transparently; a % is added to the end of the line to avoid unwanted spaces. You 
can safely use this feature to change fonts or to change the value of \baseiineskip. Anything else may well produce undesir¬ 
able results use at your own risk. Lines beginning with a period are not given any special treatment. 


COMMANDS 

for variable = expr 1 to expr2 
by [*]expr3] do X body X 
[Set var i abl e to exprl 


if expr then X if-1rue X 
[else Y i f■f a I se Y ] 




command 


sh X command X 
copy "filename" 

copy ["f i I ename"] thru X body X 
[until "word"] 

copy ["filename"] thru macro 
[until "word"] 


W hile the value of vari able is less than or equal to expr 2 , do body and increment 
va r i abl e by expr 3; if by is not given, increment vari abl e by 1 . If expr 3 is prefixed 
by * then variable will instead be multiplied by expr 3 . x can be any character not 
occurring in body. 

Evaluate ex pr; if it is nonzero,do i f -1 r u e; otherwise do i f ■ f ai se. u can beany 
character not occurring in i f ■ t r ue. y can be any character not occurring in i f - f ai se. 
Concatenate the arguments and print as a line on stderr. Each ar g must be an 
expression, a position, or text. This is useful for debugging. 

Concatenate the arguments and pass them through asa line to troff orTeX. Each 
a r g must be an expression, a position, or text. T his has a similar effect to a line 
beginning with . or \, but allowsthe values of variablesto be passed through. 
Passcommand toashell. x can beany character not occurring in command. 

Indudef 1 ename at this point in the file. 

This construct does body once for each line of f i 1 ename; the line is split into blank- 
delimited words, and occurrences of $ i in body , for i between 1 and 9, are replaced 
by the i -th word of the line If fi 1 ename is not given, lines are taken from the current 
input up to .pe. If an until clause is specified, lines will be read only until a line the 
first word of which iswor d; that line will then be discarded, x can beany character 
not occurring in body. For example 








Arguments of the form 

XanythingX 

are also allowed to be of theform: 


The commands to be performed for each line can also betaken from a macro 
defined earlier by giving the name of the macro as the argument to thru. 

Reset predefined variablesvari abi ei , va r i a bi e2 ... to their default values If no 
arguments are given, reset all predefined variablesto their default values. Note that 
assigning a value to scale also causes all predefined variables that control dimensions 
to be reset to their default values times the new value of scale. 

T his is a text object which is constructed by using as a format string for text sprintf 
with an argument of expr . If text isomitted, a format string of %g isused. Attributes 
can be specified in thesameway as fora normal text object. Bevery careful that you 
specify an appropriate format string; pic does only very limited checking of the 
string. This is deprecated in favor of sprintf. 

This is similar to = except vari able must already be defined, and the value of 
variable will be changed only in the innermost block in which it isdefined. (By 
contrast, = defines the variable in the current block if it is not already defined there, 
and then changes the value in thecurrent block.) 


In thiscase anything can contain balanced occurrences of and .br. Strings may contain x or imbalanced occurrences of 


EXPRESSIONS 

The syntax for expressions has been significantly extended: 
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el && e2 
el || e2 
el == e2 
el != e2 
el >= e2 

el <= e2 
el < e2 
"str1"=="str2" 

String comparison expressions must be parenthesized in some contexts to avoid ambiguity. 

OTHER CHANGES 

A bare expression, expr, is acceptable as an attribute; it is equivalent to di rexpr, wheredi r is the current direction. For 
example 

line 2i 

meansdraw a line 2 incheslongin the current direction. 

The maximum width and height of the picture are taken from the variables maxpswid andmaxpsht. Initially, these have values 
8.5 and 11. 

Scientific notation is allowed for numbers For example 

x = 5e-2 

T ext attributes can be compounded. For example 

"foo" above ljust 

is legal. 

There is no limit to the depth to which blocks can be examined. For example 

[A: [B: [C: box ]]] with .A.B.C.SW at 1,2 
circle at last [].A.B.C 

is acceptable. 

Arcs now have compass points determined by the circle of which the arc isa part. 

C ircles and arcs can be dotted or dashed. I n mode, splines can be dotted or dashed. 

Boxes can have rounded corners. The rad attribute specifies the radius of the quarter-circles at each corner. If no rad or diam 
attribute isgiven, a radius of boxrad is used. Initially, boxrad has a value of 0. A box with rounded corners can be dotted or 
dashed. 

The .ps line can have a second argument specifying a maximum height for the picture. If the width of zero is specified, the 
width will be ignored in computing the scaling factor for the picture. NotethatGNU pic will always scale a picture by the 
same amount vertically as horizontally. This is different from theD WB 2.0 pic, which may scale a picture by a different 
amount vertically than horizontally if a height is specified. 

Each text object has an invisible box associated with it. The compass points of a text object are determined by this box. The 
implicit motion associated with the object is also determined by this box. Thedimensionsof this box are taken from the 
width and height attributes; if the width attribute is not supplied, then the width will betaken to betextwid; if the height 
attribute isnot supplied, then the height will betaken to bethe number of text strings associated with theobject times 
textht. I nitially textwid and textht have a value of 0. 

In places where a quoted text string can be used, an expression oftheform: 
sprintf (f or mat ,a r g ,... ) 



can also be used; this will produce the arguments formatted according to for mat .which should beastring as described in 
printf (3), appropriate for the number of arguments supplied, using only the e, f, g, or % format characters 
Thethickness of the lines used to draw objects iscontrolled by the linethick variable. Thisgives the thickness of lines in 
points A negative value means use the default thickness in output mode, this means use a thickness of 8 milli-inches in 
output mode with the -c option, this means use the line thickness specified by .ps lines; in troff output mode thismeans 
use a thickness proportional to the point size. A zero value meansdrawthethinnest possible line supported bytheoutput 
device Initially, ithasavalueof -i.Thereisalso a thickness] attribute. For example, 

circle thickness 1.5 

would draw a circle usi ng a line with a thickness of 1.5 points T he thickness of lines is not affected by the value of the scale 
variable nor by the width or height given in the .ps line. 

Boxes (including boxes with rounded corners), circles, and ellipses can be filled by giving then an attribute of mi[ed]. This 
takes an optional argument of an expression with a value between 0 and 1 ; 0 will fill it with white 1 with black, values in 
between with a proportionally gray shade. A value greater than 1 can also be used: this meansfill with the shade of gray that 
is currently being used for text and lines Normally this will be black, but output devices may providea mechanism for 
changing this. Without an argument, then the value of the variable mivai will be used. Initially, thishasa valueof 0 . 5 . The 
invisible attribute does not affect thefilling of objects. Any text associated with a filled object will be added after theobject 
has been filled, so that thetext will not be obscured by thefilling. 

Arrowheads will be drawn as solid triangles if the variable arrowhead is nonzero and either mode is enabled or the -x option 
has been given. Initially, arrowhead hasavalueof 1 . 

The troff output of pic is device-independent. The-T option is therefore redundant. All numbers are taken to be in inches 
numbers are never interpreted to be in troff machine units. 

Objects can have an aligned attribute. This will only work when the postprocessor isgrops. Any text associated with an 
object having the aligned attribute will be rotated about the center of the object so that it is aligned in the direction from the 
start point to the end point of theobject. Note that this attribute will have no effect for objects whose start and end points 
are coincident. 

In places where nth is allowed, expr 'th isalso allowed. Note that ■ th is a single token: no space is allowed between the ■ and 
theth. For example, 

fori =1 to 4 do{ 


FILE 

/usr/iib/groff/tmac/tmac.pic Sampledefinitionsof the PS and PE macros. 

SEE ALSO 

gtroff(l), groff_out(5), tex(l) 

TPIC: PIC for AT&T Bell Laboratories, Computing Science Technical ReportNo. 116, PIC— A Graphics Language for 
Typesetting. (This can be obtained by sending an e-mail message to netiib@research.att.com with a body of "send 116 from 
research/cstr.") 

BUGS 

Input characters that are illegal forgroff (those with ASCII code 0 or between 013 and 037 octal or between 0200 and 0237 
octal) arerqacted even in mode. 

The interpretation of f nival is incompatible with the pic in 10th edition UNIX, which interprets 0 as black and 1 as white. 



Parti: User Commands 


216 


gprof 

gprof — D isplay call graph profile data 

SYNOPSIS 

gprof [ -abcsz ] [ -ej-E name ] [-fj-F name ][-k fromname toname ] [ objfile [ g mo n. out ]] 


DESCRIPTION 

gprof produces an execution profile of C, Pascal, or Fortran77 programs. The effect of called routines is incorporated in the 
profile of each caller. The profile data is taken from the cal I graph profile file (gmon.out default), which is created by programs 
that are compiled with the-pg option of cc(l), pc(l),and f77< 1). The-pg option also links in versions of the library routines 
that are compiled for profiling, gprof reads thegiven object file (the default is a. out) and establishes the relation between its 
symbol tableand the call graph profile from gmon.out. If more than one profile file is specified, the gprof output shows the 
sum of the profile information in thegiven profile files 

gprof calculates the amount of time spent in each routine. Next, these timesare propagated along the edges of the call graph. 
Cycles are discovered, and calls into a cycle are made to share the time of the cycle. The first listing shows thefunctions 
sorted according to the time they represent, including the time of their call graph descendants Below each function entry is 
shown its(direct) call graph children, and how their times are propagated to thisfunction. A similar display above the 
function shows how thisfunction'stime and the time of its descendants is propagated to its (direct) call graph parents. 

C ydes are also shown, with an entry for the cycle as a whole and a listing of the members of the cycle and their contributions 
to the time and call counts of the cycle. 

Second, aflat profile is given, similar to that provided by prof (1). This listing gives the total execution times, the call counts, 
thetimein milliseconds, the call spent in the routine itself, and thetimein millisecondsthecall spent in the routine itself, 
including its descendants 

Finally, an index of the function names is provided. 


OPTIONS 


Thefollowing options are available: 


Suppressesthe printing of statically declared functions Ifthisoption is given, all relevant information 
about the static function (for example, time samples, calls to other functions calls from other 
functions) belongs to the function loaded just before the static function in the objfiie file. 
Suppressesthe printing of a description of each field in the profile. 

Thestatic call graph of the program isdiscovered by a heuristic that examines thetext space of the 
object file Static-only parents or children are shown with call counts of 0. 

Suppresses the printing of the graph profile entry for routine n a me and all its descendants (unless they 
have other ancestors that aren't suppressed). M ore than one-e option may be given. 0 nly one name 
may be given with each -e option. 

Suppresses the printing of thegraph profile entry for routine name (and its descendants) as-e, 
previously and also excludes the time spent in name (and its descendants) from the total and percentage 
time computations (For example, -e mount -e mcieanup is the default.) 

Prints the graph profile entry of only the specified routine name and its descendants M ore than one-f 
option may be given. Only onename may begiven with each -f option. 

Prints the graph profile entry of only the routine name and its descendants (as -f, previously) and also 
uses only the times of the printed routinesin total time and percentage computations. M ore than one 
-f option may begiven. Only one name may begiven with each -f option. T he -f option overrides the 
-e option. 

Will delete any arcs from routinef romname to routine toname. Thiscan be used to break undesired 
cycles M ore than one-k option may begiven. Only one pair of routine names may begiven with each 
-k option. 
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A profile file gmon.sum isproduced that represents thesum of the profile information in all thespecified 
profile files Thissummary profile file may be given to later executions of gprof (probably also with an 
-s) to accumulate profiledata across several runs of an objfiie file 
Prints the version number for gprof, and then exits 

Displays routines that have zero usage (as shown by call counts and accumulated time). This is useful 
with the-c option for discovering which routines were never called. 


FILES 

a.out The name list and text space 

gmon.out Dynamic call graph and profile 

gmon.sum Summarized dynamic call graph and profile 

SEE ALSO 

monitor(3), profil(2), cc(l), prof(l) 

"An Execution Profiler for M odular Programs," by S. Graham, P. Kessler, M . McKusick; Software- Practice and Experience, 

Vol. 13, pp. 671-685,1983. 

"gprof: A Call Graph Execution Profiler," by S. Graham, P. Kessler, M . M cKusick; ProceedingsoftheSIGPLAN '82 
Symposium on Compiler Construction, SIGPLAN Notices Vol. 17, No 6, pp. 120-126, June 1982. 

HISTORY 

gprof appeared in 4.2 BSD. 

BUGS 

The granularity of the sampling isshown, but remains statistical at best. We assume that the time for each execution of a 
function can be expressed by the total time for the function divided by the number of times the function is called. Thus the 
time propagated along the cal I graph arcsto thefunction's parents is directly proportional to the number of times that arc is 
traversed. 

Parents that are not themselves profiled will have the time of their profiled children propagated to them, but they will appear 
to be spontaneously invoked in thecall graph listing, and will not have their ti me propagated further. Similarly, signal 
catchers even though profiled, will appear to be spontaneous (although for more obscure reasons). Any profiled children of 
g'gnal catchers should have theirtimes propagated properly, unless the signal catcher was invoked during theexecution of the 
profiling routine in which case all is lost. 

The profiled program must call exit(2) or return normally for the profiling information to be saved in the gmon.out file. 

29 January 1993 


grefer 

grefer- Preprocess bibliographic references for groff 

SYNOPSIS 

grefer [ - benvCPRSl [-a n] [-c fields] [-f n] [-1 fields] |-k field] [-1 m,n] [-p filename] ]-s fields] ]-t n] [-B 
field.macro] [f I I ename ...] 

DESCRIPTION 

This file documents the GN U version of refer, which is part of the groff document formatting system, refer copies the 
contentsoff 1 1 ename ... to thestandard output, except that lines between .[ and .] are interpreted as citations, and lines 
between .ri and .R 2 are interpreted ascommands about how citations are to be processed. 
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Each citation specifies a reference. The citation can specify a reference that is contained in a bibliographic database by giving 
a set of keywords that only that reference contains. Alternatively, it can specify a reference by supplying a database record i n 
thecitation. A combination of these alternatives is also possible. 

For each citation, refer can produce a mark in the text. This mark consists of some label that can be separated from the text 
and from other labels in various ways. For each reference, it also outputsgroff commands that can be used by a macro 
package to produce a formatted reference for each citation. T he output of refer must therefore be processed using a suitable 
macro package The-ms and -me macrosareboth suitable. Thecommandsto format a citation's reference can be output 
immediately after thecitation, or the references may be accumulated, and the commands output at some later point. If the 
references are accumulated, then multiplecitationsof the same reference will produce a single formatted reference 
The interpretation of lines between .ri and .R2ascommandsisanewfeatureofGNU refer. Documents making use of this 
feature can still be processed by UN IX refer just by adding the lines: 

■ ig R 2 


to the beginning of the document. This will cause troff to ignore everything between .ri and .R2. The effect of some 
commandscan also be achieved by options. These options are supported mainly for compatibility with UNIX refer. It is 
usually more convenient to use commands. 

refer generates .if lines so that filenames and line numbers in messages produced by commands that read refer output will 
be correct; it also interprets lines beginning with .if so that filenames and line numbers in the messages and .if lines that it 
produces will be accurate even iftheinput has been preprocessed by acommand such asgsoeiim(l). 

OPTIONS 

M ost options are equivalent to commands (for a description of these commands, see "Commands," later in this manual 
page): 

-b no-label-in-text; no-label-in-reference 

-e accumulate 

-n no-default-database 

-C compatible 

-P move-punctuation 

-S label "(A.njQ) 1 (D.yjD)"; bracket-label " (" ) " 

-an reverse An 

-of i el (Is capitalize fields 

rffS label %n 

-if i el ds search-ignore fields 

-k label L%a 

-kfield, label f i el d%a 

-1 label A.nD.y%a 

-lm label A.n+mD.y%a 

-l,n label A.nD.y-n%a 

-lm,n label A.n+mD.y-n%a 

-pfilename database f i I ename 

-tr search-truncate n 


These options are equivalent to thefollowing commands with theaddition that the filenames specified on the command line 
are processed as if they were arguments to the bibliography command instead of in the normal way: 


no-label-in-reference 
macro; no-label-in-reference 


Annotate 

Annotate 
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T hefollowing options have no equivalent commands: 

-v Print the version number 

-r Don't recognize lines beginning with .ri/.r2 


USAGE 

BIBLIOGRAPHIC DATABASES 

The bibliographic database is a text file consisting of records separated by one or more blank lines Within each record, fields 
start with a % at the beginning of a line Each field has a one-character name that immediately follows the*. 11 is best to use 
only uppercase and lowercase lettersfor the names of fields. The name of thefield should be followed by exactly one space 
and then by the contents of thefield. Empty fields are ignored. The conventional meaning of each field isasfollows: 
a The name of an author. If the name containsa title such asjr. at the end, it should be separated from the 

last name by acomma. There can be multi pie occurrences of theA field. The order is significant. It isa 
good idea always to supply an a field or a q field. 
b For an article that is part of a book, the title of the book, 

c The place (city) of publication. 

d The date of publication. Theyear should be specified in full. If the month is specified, the name rather 

than the number of the month should be used, but only thefirst three letters are required. 11 is a good idea 
always to supply a d field; if the date is unknown, a value such as in press or unknown can be used. 
e For an article that is part of a book, the name of an editor of the book. W here the work has editors and no 

authors, the names of the editors should be given as a fields (ed) or (eds) should be appended to the last 
author. 

g U .S. government ordering number, 

i The publisher (issuer), 

j For an article in a journal, the name of the journal. 

k Keywords to be used for searching. 

l Label. 

n J ournal issue number. 

o Other information. This is usually printed attheend of the reference 

p Pagenumber. A range of pages can be specified asm-n. 

q The name of the author, if the author is not a person. This will only be used if there are no a fields There 

can only be one q field. 
r Technical report number, 

s Series name. 

t Title. For an article in a book or journal, this should be the title of the article, 

v Volume number of the journal or book, 

x Annotation. 

For all fieldsexceptAand e, if there is more than one occurrence of a particular field in a record, only the last such field will 
be used. 

If accent strings are used, they should follow the character to be accented. T his means that the am macro must be used with 
the -ms macros Accent strings should not be quoted: use one \ rather than two. 

CITATIONS 

The format of a citation is 

- [openi ng-text 



Parti: User Commands 


220 


Theopeni ng-text,ci osi ng-text, and flags components are optional. 0 nly one of the tey words and fields components need 
be specified. 

The key words component says to search the bibliographic databases for a reference that contains all the words in keywor ds . It 
is an error if more than one reference if found. 

Thef i ei ds components specifies additional fields to replace or supplement those specified in the reference When references 
are being accumulated and thekey words component is nonempty, then additional fields should be specified only on the first 
occasion that a particular reference is cited, and will apply to all citations of that reference. 

Theopeni ng-text and c i os i ng-1 ext component specifiesstringsto be used to bracket the label instead of the strings specified 
in the bracket-label command. If either of these components is nonempty, the strings specified in the bracket-label 
command will not be used; this behavior can be altered using the [ and ] flags. Notethat leading and trailing spaces are 
significant for these components 

Thet i ags component is a list of nonalphanumeric characters, each of which modifies the treatment of this particular 
citation. UNIX refer will treat these flags as part of the keywords and so will ignore them because they are 
nonalphanumeric. T hefollowing flags are currently recognized: 

# This says to use the label specified by the short-label command, instead of that specified by the label command. 

If no short label has been specified, the normal label will be used. T ypically, theshort label is used with author- 
date labels and consists of only thedate and possibly a disambiguating letter; the# issupposed to be suggestive of 
a numeric type of label. 

[ Precede openi ng-text with thefirst string specified in the bracket-label command. 

1 Follow ci osi ng-text with thesecond string specified in the bracket-label command. 

One advantage of using the [ and ] flags rather than including the brackets in openi ng-text and ci osi ng-text is that you can 
change the style of bracket used in the document just by changing the bracket-label command. Another advantage is that 
sorting and merging of citations will not necessarily be inhibited if the flags are used. 

If a label isto be inserted into the text, it will be attached to the line preceding the.[ line. If there is no such line then an 
extra line will be inserted before the.[ line and a warning will be given. 

T here is no special notation for maki ng a citation to multiple references. J ust use a sequence of citations, one for each 
reference. Don't put anything between the citations. The labels for all the citations will be attached to the line preceding the 
first citation. The labels may also be sorted or merged. (See the description ofthe<> label expression, and of the sort- 
adjacent- labels and abbreviate-label-ranges command.) A label will not be merged if its citation hasa nonempty open ng- 
text orci osi ng-text . FI owever, the labels for a citation using the] flag and without any ci osi ng-text immediately followed 
by a citation using the [ flag and without any openi ng-text may be sorted and merged even though thefirst citation's 
openi ng-text or the second citation'sci osi ng-text is nonempty. (If you want to prevent this, just make the first citation's 


COMMANDS 

Commands are contained between lines starting with .ri and ,R2. Recognition of these lines can be prevented by the -r 
option. When an .ri line is recognized, any accumulated references are flushed out. Neither .ri nor .R2 lines, nor anything 
between them, is output. 

C ommands are separated by newlines or semicolons # introduces a comment that extends to the end of the line (but does 
not conceal the newline). Each command is broken up into words. W ords are separated by spaces or tabs A word that begins 
with an open quote (") extends to the next close quote (") that is not followed by another open quote ("). If there is no such 
open quote (") the word extends to theend of the line. Pairs of open quotes (") in a word beginning with collapse to a single 
open quote ("). Neither # nor; is recognized inside open quotes ("). A line can be continued by ending it with \; this works 
everywhere except after a #. 

Each command name thatismarked with * has an associated negative command no-name that undoestheeffect of name. For 
example, the no-sort command specifies that references should not be sorted. The negative commands take no arguments. 




In the following description, each argument must be a single word; field is used for a single uppercase or lowercase letter 
naming a field; fields is used for a sequence of such letters; m and n are used for a nonnegative numbers; string is used for an 
arbitrary string; f i i ena me is used for the name of a file. 

abbreviate*f i ei dsstringi Abbreviate thefirst names of f i ei ds . An initial letter will be separated from another 

st r i ng 2 string3st r i ng4 initial letter by st r i ng i , from the last name by s t r i ng2 , and from anything else (such 

asavonorde) by st r i ng 3. These default to a period followed by a space In a 
hyphenated first name the initial of thefirst part of the name will be separated from 
the hyphen by st r ng4; this defaults to a period. No attempt is made to handle any 
ambiguities that might result from abbreviation. N ames are abbreviated before 
sorting and before label construction. 

abbreviate -label- ranges*s t r i ng Three or more adjacent labels that refer to consecutive references will be abbreviated 
to a I abel consisting of the first label, followed by s t r i n g , followed by the last Iabel. 
This is mainly useful with numeric labels If st r i ng is omitted it defaults to -. 
accumulate* Accumulate references instead of writing out each reference as it is encountered. 

Accumulated references will be written out whenever a reference of the form: 

■ [ 

$LIST$ 


annotate*f 


articlesstri ng ... 

bibliographyf i I e n a me 
bracket-labelst ring 
1string2st ri n g 3 


compatible* 


date-as-label*st r 


i ng 


default-database* 


is encountered, after all input files have been processed, and whenever an .ri line is 
recognized. 

field is an annotation; print it at the end of the reference as a paragraph preceded by 

the line 

.string 

If macro is omitted, it will default to Ap;if field is also omitted, it will default to x. 
Only one field can bean annotation. 

These are definiteor indefinite articles, and should beignored atthebeginning ofT 

fields when sorting. Initially, the, a, and an are recognized as articles 

Write out all the references contained in the bibliographic databasesf i ename ... 

I n the text, bracket each label with s t r i n g 1 and s t r i n g 2 . A n occurrence of s t r i n g 2 
immediately followed by st ri ngi will be turned into stri ng 3. The default behavior is 
bracket-label \*([. \*(.]"," 

Convert fields to caps and smal I caps. 

Recognize .ri and .R2 even when followed by a character other than space or 
newline 

Search the bibliographic databases f i 1 ename ... For each fi 1 ename if an index 
fi 1 ename .i created by gindxbib(l) exists, then it will be searched instead; each index 
can cover multipledatabases. 

string isa label expression that specifiesa string with which to replacethe d field 
after constructing the label. See "Label Expressions" later in this manual page, fora 
description of label expressions This command is useful if you do not want explicit 
labels in the reference list, but instead want to handle any necessary disambiguation 
by qualifying the date in someway. The label used in the text would typically be 
some combination of the author and date. In most cases you should also use the no - 
iabei-in-reference command. For example, 

date-as-label D.+yD.y%a*D.-y 

would attach a disambiguating letter to the year part of theD field in the reference 
The default database should be searched. T his isthedefault behavior, so the negative 
version of this command is more useful, refer determines whether the default 
database should be searched on thefirst occasion that it needs to do a search. Thus, a 
no-defauit-database command must be given before then, in order to be effective 
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et-al*s tri n g mn 


includef i I ename 
join-authorsst r i ngl 
string2st r i ng3 


label-in-reference* 

label-in-text* 

labelst r i ng 

separate -label - second - parts 
move-punctuation* 

reverse'str i ng 

search-ignore*f i el ds 
search-truncate*n 

short-label*st r i ng 


sort-adjacent-labels* 


When the reference is read, fi el ds should be discarded; no string definitions for 
fields will be output. Initially, fi ei ds arexYz. 

Control useofetal in the evaluation of @ expressions in label expressions If the 
number of authors needed to make the author sequence unambiguous is u and the 
total number of authors ist, then the last t - u authors will be replaced by s t r i ng, 
provided that t - u is not less than mandt is not less than n. The default behavior is 

et-al " et al" 2 3. 

Includef i ename and interpret thecontentsascommands. 

Thissayshow authors should bejoined together. When there are exactly two 
authors they will bejoined with stri ngi. When there are more than two authors, all 
but the last two will bejoined with s t r i ng 2 , and the last two authors will bejoined 
with stri ng3. If stri ng3 is Omitted, it Will default to s t r i ngl; if s t r i ng2 isalSO 
omitted, itwill also default to st r i ngi. For example 
join-authors " and " ", " ", and " 

will restore the default method for joining authors. 

When outputting the reference definethestring [F to be the reference's label. This 
is the default behavior; so the negative version of this command is more useful. 

For each reference output a label in the text. The label will be separated from the 
surrounding text as described in the bracket -label command. T his isthe default 
behavior; so the negative version of thiscommand ismore useful, 
stri ng isa label expression describing how to label each reference 
W hen merging two-part labels separate the second part of the second label from the 
first label with string. See the description of the <> label expression. 

In thetext, move any punctuation attheend of line past the label. It is usually a 
good idea to give this command unless you are using superscripted numbers as 
labels 

Reverse thefields whose names are in stri ng. Each field name can be followed by a 
number that says how many such fields should be reversed. If no number is given for 
afield, all such fields will be reversed. 

While searching for keys in databases for which no index exists ignore the contents 
oft ei ds. Initially, fields xyz are ignored. 

Only require the first n charactersof keys to be given. In effect, when searching for a 
given key, words in the database are truncated to the maximum of n and the length 
of the key. Initially, n is 6. 

string isa label expression that specifiesan alternative (usually shorter) style of label. 
This is used when the# flag is given in the citation. When using author-date style 
labels the identity of the author or authors issometimes clear from the context, and 
so it may be desirable to omit the author or authors from the label. T he short - label 
command will typically be used to specify a label containing just a date and possibly 
a disambiguating letter. 

Sort references according to string. References will automatically be accumulated, 
stri ng should be a list of field names each followed by anumber, indicating how 
many fields with the name should be used for sorting. + can be used to indicate that 
all the fields with the name should be used. Also, . can be used to indicate the 
references should be sorted using the (tentative) label. (T he "Label Expressions" 
subsection describes the concept of a tentative label.) 

Sort labels that are adjacent in thetext according to their position in the reference 
list. ThiSCOmmand Should usually be given if theabbreviate-label-ranges 
command has been given, or if the label expression containsa <> expression. This 
will have no effect unless references are being accumulated. 
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LABEL EXPRESSIONS 


Label expressions can be evaluated both normally and tentatively. The result of normal evaluation is used for output. The 
result of tentative evaluation, called the tentative label, isused to gather the information that normal evaluation needs to 
disambiguate the label. Label expressions specified by the date-as-label and short-iabei commands are not evaluated 
tentatively. Normal and tentative evaluation are the same for all types of expression other than @, *, and % expressions The 
following description applies to normal evaluation, except where otherwise specified. 


field,field n 





exprl&expr 2 
exprl?expr 2 :expr 3 


The nth part of field. If n isomitted, it defaults to i. 

T he characters in s t r i n g literally. 

All the authors joined as specified by thejoin-authors command. The whole of each author'sname 
will be used. H owever, if the references are sorted by author (that isthe sort specification starts with 
A+),then authors' last names will be used instead, provided that this does not introduce ambiguity, and 
also an initial subsequence of the authors may be used instead of all the authors, again provided that 
this does not introduce ambiguity. T he use of only the last name for the i -th author of some reference 
is considered to be ambiguous if there is some other reference such that the first i - i authors of the 
references are the same, the i-th authors are not the same, but the i-th authors' last names are the 
same. A proper initial subsequence of the sequence of authors for some reference isconsidered to be 
ambiguous if there is a reference with some other sequence of authors that also has that subsequence as 
a proper initial subsequence W hen an initial subsequence of authors is used, the remaining authors are 
replaced by the string specified bytheet-ai command; this command may also specify additional 
requirements that must be met before an initial subsequence can be used. @ tentatively evaluates to a 
canonical representation of theauthors, such that authors that compare equally for sorting purpose will 
havethesame representation. 

T he serial number of the reference formatted according to the character following the %. T he serial 
number of a reference is i plusthenumber of earlier references with same tentative label as this 
reference. These expressions tentatively evaluate to an empty string. 

If there is another reference with the same tentative label as this reference, then expr ; otherwise, an 
empty string. It tentatively evaluates to an empty string. 

T he first (+) or last (-) n uppercase or lowercase letters or digits of expr. troff special characters (such 

as \ ( 1 a > count as a single letter. Accent strings are retained but do not count toward the total. 

expr converted to lowercase 

expr converted to uppercase 

expr converted to caps and small caps. 

expr reversed so that the last name is first. 

expr with first names abbreviated. Note that fields specified in the abbreviate command are abbrevi¬ 
ated before any labels are evaluated. Thus .a is useful only when you want a field to be abbreviated in a 
label but not in a reference. 

The year part of expr. 

Thepartof expr before the year, orthewholeof expr if it does not contain a year. 

Thepartof expr after the year, or an empty string if expr does not contain a year. 

The last name part of exp r . 

expr i except that if the last character of expr i is-then it will be replaced by expr 2 . 

T he concatenation of expr 1 and expr 2. 

If expr 1 is nonempty, then ex pr 1 ; otherwise, expr 2. 

If expr 1 is nonempty, then expr 2; otherwise, an empty string. 

If expr 1 is nonempty, then expr 2; otherwise, expr 3. 

The label is in two parts, which are separated by expr. Two adjacent two-part labels that havethesame 
first part will be merged by appending the second part of the second label onto thefirst label separated 
by the string specified in theseparate-iabei-second-parts command (initially, a comma followed by a 
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space); the resulting label will also be a two-part label with the same first part as before merging, and so 
additional labdscan demerged into it. N otethat it is permissible for the first part to be empty; this 
may be desirable for expressions used i n the short - label command. 

(expr ) T he same as e*pr. Used for grouping. 

The preceding expressions are I i sted in order of precedence (highest first); & and | have the same precedence 

MACRO INTERFACE 

Each reference starts with a call to the macro ] -. The string if will be defined to be the label for this reference unless the no - 
iabei-in-reference command has been given. There then follows a series of string definitions, onefor each field: string [X 
corresponds to field x. The number register [p isset to i ifthepfieldcontainsarangeofpages.The[T, [A,and [onumber 
registers are set to i according as the t, a, and o fields end with one of the characters.?!. The [e number register will beset 
to 1 if the [E string contains more than one name The reference isfollowed by a call to the ] [ macro. Thefirst argument to 
this macro gives a number representing the type of the reference. If a reference containsaj field, it will be classified as type 1; 
otherwise if it containsa b field, it will be type 3; otherwise, if it contains a G or R field it will be type 4, otherwise if it 
contains an i field, it will be type 2; otherwise it will be type 0. The second argument is a symbolic name for the type other, 
journal-article, book, articie-in-book, or tech-report. G roups of references that have been accumulated or are produced by 
the bibliography command are preceded by a call to the ]< macro and followed by a call to the ]> macro. 

FILES 

/usr/dict/papers/ind Default database 
fi i e.i Index files 

SEE ALSO 

gindxbib(l), glookbib(l), lkbib(l) 

BUGS 

In label expressions, <> expressions are ignored inside .char expressions. 

Groff Version 1.09 


grep, egrep, fgrep 

grep, egrep, fgrep— Print lines matching a pattern 

SYNOPSIS 

grep [ -[ [AB] ]num ] [-[CEFGVBchilnsvwx]][-e ] pattern j -ff i I e ] [f i I es... ] 

DESCRIPTION 

grep searches the named input files (or standard input if no files are named, orthefilename- isgiven) for lines containing a 
match to the given pattern. By default, grep prints the matching lines 
T here are three major variants of grep, controlled by the following options 

-g Interpret pat tern as a basic regular expression (see the list following this one). This isthe default. 

-e Interpret pat tern as an extended regular expression. 

-f Interpret pat tern as a list of fixed strings separated by newlines any of which is to be matched. 

In addition, two variant programs, egrep and fgrep, are available egrep issimilar (but not identical) to grepn-E, and is 
compatible with the historical UN IX egrep. Fgrep isthesameasgrepn-F. 

All variants of grep understand thefollowing options 
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-num M atches will be printed with num lines of leading and trailing context. However, grep will never print 

any given line more than once. 

-a num Print num linesoftrailing context after matching lines. 

-b num Print num linesof leading context before matching lines 

-c Equivalentto-2. 

-v Print the version number of grep to standard error. This version number should be included in all bug 

reports. 

-b Print the byte offset within the input file before each line of output. 

-c Suppress normal output; instead print a count of matching linesfor each input file. With the-v 

option, count nonmatching lines 

-e pattern Usepatt er n asthe pattern; useful to protect patterns beginning with -. 

-f file 0 btain the pattern from file. 

-h Suppresstheprefixingoffilenameson outputwhen multiple files are searched. 

-i Ignore casedistinctionsin both the pat t er n and the input files 

-l Suppress normal output; instead print the name of each input file from which no output would 

normally have been printed. 

-l Suppress normal output; instead print the name of each input file from which output would normally 

have been printed. 

-n Prefix each line of output with the line number within its input file 

-q Q uiet; suppress normal output. 

-s Suppress error messages about nonexistent or unreadable files 

-v I nvert the sense of matching, to select nonmatching lines. 

-w Select only those lines containing matches that form whole words The test is that the matching 

substring must either be at the beginning of the line, or preceded by a nonword constituent character. 
Similarly, it must be either at the end of the line or followed by a nonword-constituent character. 

W ord-constituent characters are letters, digits and the underscore. 

-x Select only those matches that exactly match the whole line. 


REGULAR EXPRESSIONS 

A regular expression is a pattern that describes a set of strings. Regular expressions are constructed analogously to arithmetic 
expressions by using various operators to combine smaller expressions 

grep understands two different versions of regular expression syntax: basic and extended. I n G N U \grep, there is no difference 
in available functionality using either syntax. In other implementations basic regular expressions are less powerful. The 
following description applies to extended regular expressions; differences for basic regular expressions are summarized 
afterwards. 

Thefundamental building blocks are the regular expressions that match a single character. M ost characters including all 
letters and digits are regular expressions that match themselves Any mdta character with special meaning may be quoted by 
preceding it with a backslash. 

A list of characters enclosed by [ and ] matches any single character in that list; if the first character of the list is the caret (') 
then it matches any character notin the list. For example the regular expression [0123456789] matches any single digit. A 
range of ASC11 characters may be specified by giving thefirst and last characters separated by a hyphen. Finally, certain 
named classes of characters are predefined. Their names are self-explanatory, and they are [: ainum:],[: alpha:],[: cntn:], 

[: digit: ], [ :graph: ], [ :lower: ], [ :print: ], [ipunct:], [ :space: ], [: upper: ], and [: xdigit: ]. For example, [ [ :alnum: ] ] 
means [o-9A-za- z], except the latter form isdependent upon the ASC 11 character encoding, whereas the former is portable. 
(N otethat the brackets in these class names are part of the symbolic names, and must be included in addition to the brackets 
delimiting the bracket list.) M ost meta characters lose their special meaning inside lists To include a literal ], place it first in 
the list. Similarly, to include a literal \ place it anywhere but first. Finally, to include a literal place it last. 

The period matchesany single character. The symbol \w is a synonym for [ [ :ainum: ] ] and \wisa synonym for [*[: ainum]]. 
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The caret and the dollar sign are meta characters that respectively match the empty string at the beginning and end of a line. 
T he symbols\< and \>, respectively, match the empty string at the beginning and end of a word. The symbol \b matchesthe 
empty string at the edge of a word, and \b matchesthe empty string provided it's not at the edge of a word. 

A regular expression matching a single character may be followed by one of several repetition operators 
? The preceding item isoptional and matched at most once 

* The preceding item will be matched zero or more times 

+ Thepreceding item will bematched one or more times, 

n Thepreceding item is matched exactly n times 

n, Thepreceding item is matched n or more times 

,m Thepreceding item isoptional and is matched at most m times 

n ,m Thepreceding item is matched at least n times but not more than m times 

Two regular expressions may be concatenated; the resulting regular expression matches any string formed by concatenating 
two substrings that respectively match the concatenated subexpressions 

Two regular expressions may be joined by the infix operator |; the resulting regular expression matches any string matching 
either subexpression. 

Repetition takes precedence over concatenation, which in turn takes precedence over alternation. A whole subexpression may 
be enclosed in parentheses to override these precedence rules. 

The back reference \n, wheren isa single digit, matches the substring previously matched by then th parenthesized 
subexpression of the regular expression. 

In basic regular expressions, the meta characters |, (, and ) lose their special meaning; instead use the backsl ashed versions 
\?, \+, \f, \], \(, and \). 

In egrep, the metacharacter {loses its special meaning; instead use \{. 

DIAGNOSTICS 

Normally, exit status isa if matches were found, and i if no matches were found. (The .b -v option invertsthe sense of the 
exit status) Exit status is 2 if there were syntax errors in the pattern, inaccessible input files or other system errors 

BUGS 

E-mail bug reports to bug-gnu-utiis@prep. ai.mit.edu. Besureto include the word grep somewhere in the "Subject:" field. 
Large repetition counts in the m , n construct may cause grep to use lots of memory. I n addition, certain other obscure regular 
expressions require exponential time and space, and may cause grep to run out of memory. 

Back references are very slow, and may require exponential time. 

GNU Project, 10 September 1992 


grephistory 

grephistory— D isplay filenames from U senet history file 

SYNOPSIS 

grephistory [ -f filename ][-e ][-n ][-q ][-1 ][-i ][-s ][ me s s a g e i d ] 

DESCRIPTION 

grephistory queries the dbz(3) index into the history(5) file for an article having a specified M essage ID . 

If messageid cannot be found in the database, the program prints "Not found" and exits with a nonzero status. If messageid is 
in the database, the program prints the pathname and exits successfully. If no pathname exists, the program will print /dev/ 




null and exit successfully. Thiscan happen when an article has been canceled, or if it has been expired but its history isstill 
retained. This isdefault behavior, which can be obtained by using the -n flag. 

If the -q flag isused, then no message isdisplayed. The program will still exit with the appropriate exit status If the -e flag is 
used, then grephi story will only print the filename of an existing article. 

If the-l flag isused, then the entire linefrom the history file will bedisplayed. 

If the -i flag isused, then grephi story will read a list of M essage-IDson standard input, one per line Leading and trailing 
whitespace is ignored, as are any malformed lines It will print on standard output those M essage-IDs that are not found in 
the history database. This flag is used in processing ihave control messages. 

If the -s flag isused, then grephi story will read a similar list from its standard input. It will print on standard output a list of 
filenames for each article that isstill available. Thisflag isused in processing sendme control messages 
T o specify a different value for the history file and database, use the -f flag. 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

dbz(3), history(5) 

grodvi 

grodvi— Convert groff output to TeX dvi format 

SYNOPSIS 

grodvi [ -dv ][-wn ] [-Fd i r ] [files ... ] 

DESCRIPTION 

grodvi is a driver for groff that produces dvi format. Normally, it should be run by groff-Tdvi. This will run gtroff-Tdvi; it 
will also input the macros /usr/iib/groff/tmac/tmac. dvi; if the input is being preprocessed with geqn, it will also input /usr/ 

lib/groff/font/devdvi/eqnchar. 

The dvi file generated by grodvi can be printed by any correctly written dvi driver. Thetroff drawing primitives are 
implemented using the tpic version 2 specials If the driver does not support these the \d commands will not produce any 
output. 

There isan additional drawing command available 

\d 1 Rd h dv’ Draw a rule (solid black rectangle), with one corner at the current position, and the diagonally 

opposite corner atthecurrent position + (d b, d v). Afterwards, thecurrent position will be at the 
opposite corner. This produces a rule in the dvi file and so can be printed even with a driver that does 
not support the tpic specials, unlike the other \d commands 

The groff command \x'anyt hi ng 1 istranslated into the same command in the dvi file as would be produced by \speciai{ 
anything } in TeX; anyt hi ng may not contain a newline. 

Font files for grodvi can be created from tfm files using tfmtodit(l). Thefont description file should contain thefollowing 
additional commands 

internalname name The name Of the tfm file (without the .tfm extension) is name, 
checksum n The checksum in the tfm file iSn. 

designsize n Thedesignsize in thetfm file iSn. 

These are automatically generated by tfmtodit. 
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In troff,the\N escape sequence can be used to access characters by their position in the corresponding tfm file; all characters 
in the tfm file can be accessed this way. 

OPTIONS 

-d Do notusetpic specials to implement drawing commands. Horizontal and vertical lineswill beimplemented by 
rules. Other drawing commands will be ignored. 

-v Print the version number. 

-wn Set the default linethicknessto n thousandths of an em. 

-Fdi r Search directory di r / devdvi for font and device description files 

FILES 

/usr/iib/groff/font/devdvi/DESC Device description file 

/usr/iib/groff/font/devdvi/ f Font description filefor font F 

/usr/iib/groff/tmac/tmac.dvi M acrosfor usewith grodvi 

BUGS 

dvi files produced by grodvi use a different resolution (57,816 units per inch) than those produced byTeX. Incorrectly 
written drivers that assume the resolution used byTeX, rather than using the resolution specified in the dvi file, will not 
work With grodvi. 

When using the-d option with boxed tables vertical and horizontal lines can sometimes protrude by one pixel. Thisisa 
consequence of the way T eX requires that the heights and widths of rules be rounded. 

SEE ALSO 

tfmtodit(l), groff(l), gtroff(l), geqn(l), groff_out(5), groff_font(5), groff_char(7) 

Groff Version 1.09 14 


groff 

groff— Front end for the groff document formatting system 

SYNOPSIS 

groff [ -tpeszaivhblCENRVXZ] [-wname ][-Wn a me ][-mn a me ][-Fdi r ][-Td e v ] [ -f f am ][-Md i r ][-dcs ][-rcn ][-nnum ] 
[-ol i st ] [-Par g [[files ... ] 

DESCRIPTION 

groff is a front-end to the groff document formatting system. Normally, it runs the gtroff program and a postprocessor 

appropriate for the selected device. Available devices are 

ps For PostScript printers and previewers 

dvi For TeX dvi format 

xzs For a 75 dpi Xll previewer 

xi00 For a 100dpi Xll previewer 

ascii For typewriter-like devices 

latini For typewriter-like devices using the I SO Latin-1 character set. 

The postprocessor to be used for a device is specified by the postpro command in the device description file. Thiscan be 
overridden with the -x option. 

The default de/ice is ps. It can optionally preprocess with any of gpic, geqn, gtbi, grefer, orgsoeiim. 
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Options without an argument can be grouped behind a single A filename of - denotes the standard input. 

The grog command can be used to guess the correct groff command to use to format a file. 

OPTIONS 

-h Print a help message. 

-e P reprocess With geqn. 

-t Preprocess with gtbi. 

-p P reprocess with gpic. 

-s PreprOCeSSWith gsoelim. 

-r Preprocess with gref er. N o mechanism is provided for passing arguments to grefer because most gref er options 

have equivalent commands that can be included in thefile. Seegrefer(l) for more details 
-v M ake programs run by groff print out their version number. 

-v Print the pipeline on stdout instead of executing it. 

-z Suppress output from gtroff. Only error messages will beprinted. 

-z Do not postprocess the output of gtroff. Normally, groff will automatically run the appropriate postprocessor, 
-par g Passarg to the postprocessor. Each argument should be passed with a separate -p option. Note that groff does not 
prepend - to a r g before passing it to the postprocessor. 

-l Send the output to a printer. The command used for this isspecified by the print command in the device 
description file 

-Larg Passarg to thespooler. Each argument should be passed with a separate -l option. N otethat groff does not 
prepend - to a r g before passing it to the postprocessor. 

-Tdev P repare output for device d e v. T he default device is ps. 

-x Preview with gxditview instead of using the usual postprocessor. This is unlikely to produce good results except 
with -Tps. 

-n Don't allow newlines with eqn delimiters This is the same as the -n option in geqn. 

Theoptions -a, -b, -i, -C, -E, -wname, -Wname, -mname, -ol i st, -dcs, -rcn, -Fdi r, -Mdi r, -ff am, and -nnum aredeSCribed in 
gtroff(l). 


ENVIRONMENT 

GROFF_COMMAND_PREFIX 

GROFF_TMAC_PATH 

GROFF_TYPESETTER 

GR0FF_F0NT_PATH 

GROFF_TMPDIR 


If this is set x, then groff will run xtroff instead of gtroff. This also applies to tbi, pic, eqn, refer, 
and soelim. It does not apply to grops, grodvi, grotty, and gxditview. 

A colon-separated list of directories in which to search for macro files 
D efault device 

A colon-separated list of directories in which to search forthedevname directory. 

The search path for commands executed by groff. 

The directory in which temporary files will be created. If this is not set and tmpdir issdt, temporary 
files will be created in that directory. Otherwise temporary files will be created in /tmp. The 
grops(l) and grefer(l) commands can create temporary files. 


FILES 

/usr/iib/groff/font/devname /desc Device description file for device name. 
/usr/lib/groff/font/devnam^F Font file for font F of device name. 

AUTHOR 

J ames C lark ( j j c@j dark. com) 
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BUGS 

Report bugs to bug-groff@prep.ai.mit.edu. I ndude a complete, self-contained example that will allow the bug to be 
reproduced, and say which version of groff you are using. 

COPYRIGHT 

Copyright 1989,1990,1991,1992 Free Software Foundation, Inc. 

groff isfree software; you can redistribute it or modify it under theterms of theG N U General Public License as published 
by the Free Software Foundation; either version 2, or (at your option) any later version. 

groff isdistributed in the hope that it will be useful, but without any warranty; without even theimplied warranty of 
merchantability or fitness for a particular purpose. SeetheGNU General Public License for more details 
You should have received a copy of the G N U General Public License along with groff; see thefile copying. If not, write to 
the Free Software Foundation, 675 M assAve Cambridge M A 02139, USA. 

AVAILABILITY 

The most recent released version of groff is always avail able for anonymous ftp from prep.ai.mit.edu (18.71.0.38) in the 
directory pub/gnu. 

SEE ALSO 

grog(l), gtroff(l), gtbl(l), gpic(l), geqn(l), gsoelim(l), grefer(l), grops(l), grodvi(l), grotty(l), gxditview(l), 
groff_font(5), grof_out(5), groff_ms(7), groff_me(7), groff_char(7) 

Groff Verson 1.09, 29 October 1992 


grog 

grog-Guessoptionsfor groff command 

SYNOPSIS 

grog [ -option ... ] [f i I es ... ] 

DESCRIPTION 

grog reads f i i es and guesses which of the groff(l) options-e, -man, -me, -mm, -ms, -p, -s,and -t are required for printing 
fi i es, and prints the groff command including those options on the standard output. A filenameof- istaken to refer to the 
standard input. If no files are specified, the standard input will be read. Any specified options will be included in the printed 
command. N o space isallowed between options and their arguments For example, 

'grog -Tdvl paper.ms' 

will guess the appropriate command to print paper.ms and then run it after adding the-Tdvi option. 

SEE ALSO 

doctype(l), groff(l), gtroff(l), gtbl(l), gpic(l), geqn(l), gsoelim(l) 

GroffVersion 1.09 14 
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grops— PostScript driver for groff 

SYNOPSIS 

grops [ -glv ][ -bn ][-cn ][-wn ][-Fdir ] [files 



DESCRIPTION 

grops translates the output of GNU troff to PostScript. Normally, grops should be invoked by using the groff command 
with a-Tps option. If no files are given, grops will read the standard input. A filename of - will also cause grops to read the 
standard input. PostScript output is written to the standard output. When grops isrun by groff, optionscan be passed to 
grops by using the groff -p option. 

OPTIONS 

-bn Workaround broken spoolers and previewers Normally grops produces output that conforms the Document 

Structuring Conventions version 3.0. Unfortunately, some spoolers and previewers can't handle such output. The 
value of n controls what grops does to its output acceptable to such programs A value of 0 will cause grops not to 
employ any workarounds Add 1 if no %%BeginDocumentsetup and %%EndDocumentsetup comments should be 
generated; this is needed for early versions of Transcript that get confused by anything between the%%EndProiog 
comment and the first %%Page comment. Add 2 if lines in included files beginning with %! should be stripped out; 
this is needed for Sun's pageview previewer. Add 4 if %%Page, %%Traiier, and %%EndProiog comments should be 
stripped out of included files; this is needed for spoolers that don't understand the%%BeginDocument and 
%%EndDocument comments. Add 8 if the first line of the PostScript output should be %!PS-Adobe- 2.0 rather than 
%!PS-Adobe-3.0; this is needed when using Sun's Newsprint with a printer that requires page reversal. The default 
value can be specified byabrokenn command in theDESc file 0 therwise, the default value is 0 . 

-cn Print n copiesof each page. 

-g G uessthe page length. This generates PostScript code that guessesthe page length. Theguess will be correct only 
if the imageable area is vertically centered on the page. This option allows you to generate documents that can be 
printed both on letter (8.5x11) paper and on A4 paper without change 
-1 Print the document in landscape format. 

-Fdi r Search the directory dir/devn a me for font and device description files; name is the name of the device, usually ps. 

-wn Linesshould bedrawn using a thickness of n thousandthsof an em. 

-v Print the version number. 

USAGE 

There are styles called r, i, b, and bi mounted at font positions 1 to 4. The fonts are grouped into families a, bm, c, h, hn, n, 

p, and t having membersin each of these styles: 

ar AvantGarde-Book 

ai AvantGarde-BookOblique 

ab AvantGarde-Demi 

abi AvantG arde-D emiO blique 

bmr Bookman-Light 

bmi Bookman-Lightltalic 

bmb Bookman-Demi 

bmbi Bookman-Demiltalic 

cr Courier 

ci Courier-Oblique 

cb Courier-Bold 

cbi Courier-BoldO blique 

hr H elvetica 

hi Helvetica-Oblique 

hb H elvetica-Bold 

hbi H elvetica-BoldO blique 

hnr Helvetica-Narrow 

hni Helvetica-Narrow-Oblique 
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hnb Helvetica-Narrow-Bold 

hnbi Helvetica-Narrow-BoldOblique 
nr NewCenturySchlbk-Roman 

ni NewCenturySchlbk-ltalic 

nb NewCenturySchlbk-Bold 

nbi NewCenturySchlbk-Boldltalic 

pr Palatino-Roman 

pi Palatino-ltalic 

pb Palatino-Bold 

pbi Palatino-Boldltalic 

tr Times-Roman 

ti Times-ltalic 

tb Times-Bold 

tbi Times-Boldltalic 

T here is also thefollowing font which is not a member of a family: 
zcmi ZapfChancery-M ediumltalic 

There are also some special fonts called ss and s. Zapf D ingbats is available as zd and a reversed version of ZapfD ingbats 
(with symbols pointing in the opposite direction) is available as zdr; most characters in these fonts are unnamed and must be 
accessed using \n. 

grops understands various x commands produced using the\x escape sequence: grops will only interpret commands that 
begin with aps: tag. 

\x 1 ps : e x e c code 1 Thisexecutes the arbitrary PostScript commandsin code. The PostScript cumentpoint will besetto 

the position of the \nx command before executing code. T he origin will be at the top left corner of 
the page, and y coordinates will increase down the page. A procedure u will be defined that converts 
groff units to the coordinate system in effect. For example 
\X 1 ps: exec \nx u 0 rlineto stroke 1 

will draw a horizontal line one inch long, code may make changes to the graphics state but any 
changes will persist only to the end of the page A dictionary containing the definitions specified by 
def and mdef will beon top of the dictionary stack. If your code adds definitions to this dictionary, 
you should allocate space for them using \x' psmdef n 1 . Any definitions will persist only until the end 
of the page. If you use the \y escape sequence with an argument that names a macro, code can 
extend over multiple lines For example, 



\nx u 0 rlineto 
stroke 


\Yy 

is another way to draw a horizontal line one inch long. 

\x 1 ps :f m e name 1 T his is the same as the exec command except that the PostScri pt code is read from file n a me. 

\x'ps:def code' Place a PostScript definition contained in code in the prologue There should beat most one 

definition per \x command. Long definitionscan be split over several \x commands: all the code 
arguments are simply joined together separated by newlines The definitions are placed in a 
dictionary which is automatically pushed on the dictionary stack when an exec command is 
executed. If you usethe\Y escape sequence with an argument that names a macro, code can extend 
over multiple lines 
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Like def, except that code may contain up to n definitions, grops needs to know how many 
definitions code contains so that it can create an appropriately sized PostScript dictionary to contain 
them. 

Import a PostScript graphic from me. The arguments iix, By, urx, and ury give the bounding box 
of the graphic in the default PostScript coordinate system; they should all be integers iix and iiy 
are the x and y coordinates of the lower-left corner of the graphic; urx and ury are the x and y 
coordinates of the upper-right corner of the graphic; wi dth and hei ght are integers that give the 
desired width and height in groff units of the graphic. The graphic will be scaled so that it has this 
width and height and translated so that the lower-left corner of the graphic is located at the 
position associated with \x command. If the height argument is omitted, it will be scaled uniformly 
in thex and y directions so that it has the specified width. N otethat the contents of the \x 
command are not i nterpreted by troff ; so vertical space for the graphic is not automatically added, 
and thewidth and height arguments are not allowed to have attached scaling indicators If the 
PostScript file complies with the Adobe Document Structuring Conventions and containsa 
%%BoundingBox comment, then the bounding box can be automatically extracted from within groff 
by using the sy request to run the psbb command. 

The-mps macros (which are automatically loaded when grops is run by the groff command) include a pspic macro that 
allows a picture to be easily imported. This has the format: 

.PSPIC file [ -L j -R j -I n ][width [ height ]] 

file is the name of thefile containing the illustration; dth and hei ght give the desired width and height of the graphic. The 
wi dth and hei ght arguments may have scaling indicators attached; the default scaling indicator isi. This macro will scale the 
graphic uniformly in thex and y directions so that it is no more than wi dt h wide and height high. By default, the graphic will 
be horizontally centered. The-Land -r cause the graphic to be left-aligned and right-aligned, respectively. The -i option 
causes the graphic to be indented by n. 

\x'ps: invis 1 , \x'ps: endinvis 1 N o output will begenerated for text and drawing commandsthat are bracketed with 

these \X commands These commands are intended for use when output from troff will 
be previewed before being processed with grops; if the previewer is unable to display 
certain characters or other constructs then other substitute characters or constructs can 
be used for previewing by bracketing them with these \x commands 

For example, gxditview is not able to display a proper \<em character because the standard Xll fonts do not provide it; this 
problem can be overcome by executing the following request: 

.char \(em \X'ps: invis'\ 

\Z‘\v'-.25m'\h'.05m'\D‘1 .9m 0'\h'.05m"\ 

\X'ps: endinvis'\(em 

In this case gxditview will be unable to display the \ (em character and will draw the line whereas grops will print the \ (em 
character and ignore the line. 

The input to grops must be in the format output by gtroff(l). This is described in groff_out(l). In addition, the device and 
font description files for thedevice used must meet certain requirements Thedeviceand font description files supplied for 
ps device meet all these requirements, afmtodit(l) can be used to create font files from afm files The resolution must be an 
integer multiple of 72 times the sizescale. T heps device uses a resolution of 72000 and asizescaleof 1000. Thedevice 
description file should contain a command: 

paperlengthn 

which says that output should begenerated that issuitablefor printing on a page whose length isn machine units Each font 
description file must contain a command: 

internalnamepsname 

which says that the PostScript name of thefont ispsname. It may also contain a command: 

encodingenc file 




\X'ps:importfile 
llxllyu rxu rywidth 
[height] 1 




Parti: User Commands 


234 


which says that the PostScript font should be reencoded using theencoding described in enc.fi i e ; thisfile should consist of a 
sequence of li nes of the form: 


wherepscim is the PostScript name of the character, and code is its position in the encoding expressed asadecimal integer. 
The code for each character given in the font file must correspond to the code for the character in encoding file, or to the 
code in the default encoding for the font if the PostScript font is not to be reencoded. T his code can be used with the \n 
escape sequence in troff to select the character, even if the character does not have a groff name. Every character in thefont 
fi le must exist in the PostScript font, and the widths given in thefont file must match the widths used in the PostScript font, 
grops will assume that a character with a groff name of space is blank (makes no marks on the page); it can make use of such 
a character to generate more efficient and compact PostScript output. 

grops can automatically include the downloadable fonts necessary to print the document. Any downloadable fonts which 
should, when required, be included by grops must be listed in the file /usr/iib/groff/font/devps/downioad; thisshould 
consist of lines of the form: 


where font is the PostScript name of thefont, and f i i ename is the name of the file containing thefont; lines beginning with # 
and blank lines are ignored; fields may be separated by tabsor spaces; f i i ename will be searched for using the same mecha¬ 
nism that is used for groff font metric files. The download file itself will also be searched for using this mechanism. 

If the file containing a downloadable font or imported document conforms to the Adobe D ocument Structuring Conven¬ 
tions, then grops will interpret any comments in the files sufficiently to ensure that its own output is conforming. It will also 
supply any needed font resources that are listed in thedownload file aswell as any needed file resources It isalso ableto 
handle interresource dependencies For example, suppose that you have a downloadable font called Garamond, and also a 
downloadable font called Garamond-Outline that depends on Garamond (typically, it would be defined to copy G aramond's 
font dictionary, and change the PaintT ype), then it is necessary for Garamond to appear before G aramond-0 utline in the 
PostScript document, grops will handle thisautomatically provided that the downloadable font file for Garamond-0 utline 
indicates its dependence on G aramond by means of the D ocument Structuring C onventions for example by beginning with 
the following lines 
%!PS-Adobe-3.0 Resource-Font 
%%DocumentNeededResources: font Garamond 
%%EndComments 

%%IncludeResource: font Garamond 

In thiscase both Garamond and Garamond-0 utline would need to be listed in thedownload file A downloadable font 
should not include its own name in a%%DocumentsuppitedResources comment, 
grops will not interpret %%DocumentFonts comments 

The%%DocumentNeededResources, %%DocumentSuppliedResources, %%IncludeResource, %%BeginResource, and %%EndResource 
Comments (or possibly the old %%DocumentNeededFonts, %%DocumentSuppliedFonts, %%IncludeFont, %%BeginFont, and %%EndFont 
comments) should be used. 

FILES 

/usr/lib/groff/font/devps/DESC 
/usr/lib/groff/font/devps/F 
/usr/lib/groff/font/devps/download 
/usr/lib/groff/font/devps/text.enc 
/usr/lib/groff/tmac/tmac.ps 
/usr/lib/groff/tmac/tmac.pspic 
/usr/lib/groff/tmac/tmac.psold 

/usr/lib/groff/tmac/tmac.psnew 
/tmp/gropsXXXXXX 


Device description file 
Font description filefor font F 
List of downloadable fonts. 

Encoding used for text fonts 

M acrosfor use with grops; automatically loaded by troff re 
D efinition of pspic macro, automatically loaded by tmac.ps 
M acrosto disable use of characters not present in older PostScript printers; 
automatically loaded by tmac.ps 
M acrosto undo the effect of tmac.psoid 
Temporary file 
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SEE ALSO 

afmtodit(l), groff(l), gtroff(l), psbb(l), groff_out(5), groff_font(5), groff_char(7) 

GroffVersion 1.09,14 February 1995 


grotty 

grotty— grotf driver for typewriter-like devices 

SYNOPSIS 

grotty [ -hfbuodBUv ][-Fd i r ] [files ... ] 


DESCRIPTION 

grotty translates the output of GN U trott into a form suitable for typewriter-like devices Normally, grotty should invoked 
by using the groff command with a -Tascii or -Tiatini option. If no files are given, grotty will read the standard input. A 
filename of - will also cause grotty to read the standard input. Output is written to the standard output. 

Normally, grotty printsabold character c using the sequence 'c backspace c 1 and an italic character c by the sequence 
1 _backspace c' .These sequences can be displayed on a terminal by piping through ui(l). Pagers such asmore(l)oriess(l) 
are also able to display these sequences U se either -b or -u when piping into less(l); use -b when piping into more(l). There 
is no need to filter the output through coi(l) since grotty na/er outputs reverse linefeeds 
Thefont description file may contain a command: 

internalnamen 

where n isa decimal integer. If the 01 bitin n is sdt, then thefont will be treated as an italic font; if the 02 bit isset, then it 
will be treated as a bold font. The code field in thefont description field gives the code that will be used to output the 
character. This code can also be used in the \n escape sequence in trott. 


OPTIONS 

-Fdi f ; Search the directory di r / devname for font and device description files; name is the name of theda/ice, usually ascii 

Orlatinl. 

-h Use horizontal tabs in the output. T abs are assumed to be set every 8 columns 

-t Use form feeds in the output. A form feed will be output at the end of each page that has no output on its last 
line 

-b Suppress the use of overstriking for bold characters 

-u Suppress the use of underlining for italic characters 

-b U se only overstriking for bold-italic characters. 

-u U se only underlining for bold-italic characters. 

-o Suppress overstriking (other than for bold or underlined characters). 

-d Ignore all \D commands. W ithout this, grotty will render \D'i ... 1 commands that have at least one zero 
argument (and so are either horizontal or vertical) using-, ], and + characters. 

-v Print the version number. 


FILES 

/usr/lib/groff/font/devascii/DESC 
/usr/lib/groff/font/devascli/F 
/usr/lib/groff/font/devlatinl/DESC 
/usr/lib/groff/font/devlatinl/F 
/usr/lib/groff/tmac/tmac.tty 
/usr/lib/groff/tmac/tmac.tty-char 


Device description file for ascii device 
Font description filefor font f of ascii device 
Device description filefor latim device. 

Font description filefor font f of latim device. 

M acrosfor use with grotty. 

Additional kludgy character definitionsfor use with grotty. 
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BUGS 

grotty is intended only for simple documents 

T here is no support for fractional horizontal or vertical motions 

There is no support for \d commands other than horizontal and vertical lines. 

Characters above the first line (that is, with a vertical position of 0) cannot be printed. 

SEE ALSO 

groff(l), gtroff(l), groff_out( 5 ), groff_font( 5 ), groff_char( 7 ), ul(l), more(l), less(l) 

GroffVersonl.09,14 February 1995 


gsoelim 

gsoeiim— Interpret .so requestsin groff input 

SYNOPSIS 

gsoelim [ -Cv [[files ... ] 

DESCRIPTION 

gsoeiim reads f i 1 es and replaces lines of the form 
.sofile 

by the contents of fiie.lt is useful if files included with so need to be preprocessed. Normally, gsoeiim should be invoked 
with the -s option of groff. 

OPTIONS 

-c Recognize. so even when followed by a character other than space or newline 
-v Print the version number 

SEE ALSO 

groff(l) 

Groff Versonl.09,15 September 1992 


gtbl 

gtbi— Format tables for troff 

SYNOPSIS 

gtbl [ -Cv ] [files ... ] 

DESCRIPTION 

This manual page describes the GN U version of tbi, which is part of the groff document formatting system, tbi compiles 
descriptions of tables embedded within troff input files into commands that are understood by troff. Normally, it should 
be invoked using the-t option of groff. It is highly compatible with UNIX tbi. The output generated by GN U tbi cannot 
be processed with UN IX troff; it must be processed with GNU troff. If no files are given on the command line, the 
standard input will be read. A filename of - will cause the standard input to be read. 



OPTIONS 


Recognize .ts and .te even when followed by a character other than space or newline 
Print the version number 


USAGE 

Only the differences between GNU tbi and UN IX tbi are described here 

N ormally, tbi attempts to prevent undesirable breaks in the table by using diversions Thiscan sometimes interact badly 
with macro packages'own use of diversions when footnotes, for example, are used. The nokeep option tells tbi not to try to 
prevent breaks in this way. 

Thedecimaipoint option specifies the character to be recognized asthedecimal point character in place of the default period. 
It takes an argument in parentheses, which must be a single character, as for the tab option. 

Thet format modifier can be followed by an arbitrary length font name in parentheses 

There is ad format modifier that means that a vertically spanning entry should be aligned at the bottom of its range 

There is no limit on the number of columns in a table, nor any limit on the number of text blocks All the lines of a table are 

considered in deciding column widths not just the first 200. T able continuation (,t&) lines are not restricted to the first 200 

lines. 

N umeric and alphabetic items may appear in the same column. 

N umeric and alphabetic items may span horizontally. 

tbi uses register, string, macro and diversion names beginning with 3. When using tbi, you should avoid using any names 
beginning with a 3. 

BUGS 

You should use .tsh/.th in conjunction with a supporting macro package for all multipage boxed tables If there is no header 
that you want to appear at the top of each page of the table, place the .th line immediately after the format section. Do not 
enclose a multipage table within keep/release macros or divert it in any other way. 

A text block within a table must beableto fit on one page 

The bp request cannot be used to force a page-break in a multi page table Instead, define bp as follows: 

.de BP 

■le 1 \\n(.z" .bp \\$1 
.el \!.BP \\$1 

and use bp instead of bp. 

SEE ALSO 

groff(l), gtroff(l) 

Groff Version 1.09,1 April 1993 


gtroff 

gtroff— Format documents 

SYNOPSIS 

gtroff [-abivzCER] [-w n a me] [-W n a me] [-d cs] [-f f a m] [-m n a me] [-n num] [-0 list] [-r cn] [-T n a me] [-F dir] [-M 
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DESCRIPTION 

This manual page describes the GN U version of troff, which ispartofthegroff document formatting system. It is highly 
compatible with UN IX troff. Usually, it should be invoked using the groff command, which will also run preprocessors and 
postprocessors in the appropriate order and with the appropriate options 


OPTIONS 


-c 


G enerate an ASC11 approximation of the typeset output. 

Print a backtrace with each warning or error message This backtrace should help track down the cause of 
the error. The line numbers given in the backtrace may not always correct: troff’s idea of line numbers 
gets confused by as or am requests 

Read the standard input after all the named in put files have been processed. 

Print the version number. 

Enable warning name. Available warnings are described in the "Warnings" subsection as follows M ultiple 
-w options are allowed. 

Inhibit warning name. M ultiple -w options are allowed. 

Inhibit all error messages 
Suppress formatted output. 

Enable compatibility mode 

Definec or name to beastring s; c must be a one-ldtter name. 

Usef am as the default font family. 

Read in the filetmac. name. Normally, this will besearchedforin /usr/iib/groff/tmac. 

Don't load troffrc. 

N umber the first page n urn. 

Output only pages in i i st, which is a comma-separated list of page ranges; n means print pagen, m-n 
means print every page between m and n, -n means print every page up to n, n - means print every page 
from n. Troff will exit after printing the last pagein the list. 

Set number register c or name ton; c must be a one-character name; n can beany troff numeric expression. 
Prepare output for device n a me, rather than the default ps. 

Search dir for subdirectories devn a me (name isthenameof the device) for the desc file and font files before 
the normal /usr/lib/groff/font. 

Search directory di r for macro files before the normal /usr/iib/groff/tmac. 


USAGE 

Onlythefeaturesnotin UNIX troff are described here. 

LONG NAMES 

The names of number registers, fonts, strings/macros/diversions, special characters can be of any length. In escape 
sequences, where you can use (x* for a two-character name you can use [xxx] for a name of arbitrary length: 

\ [xxx ] Print the special character called xxx. 

\f [xxx ] Setfontxxx. 

\ * I x x x ] Interpolate string xxx. 

\ n [ x x x ] Interpolate number register xxx. 


FRACTIONAL POINT SIZES 

A scaled point isequal to 1/sizescale points, where sizescale is specified in the desc file (i by default.) There is a new scale 
indicator z that has the effect of multiplying by sizescale. Requests and escape sequences in troff interpret arguments that 
represent a point size as being in units of scaled points, but they evaluate each such argument using a default scale indicator 
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of z. Arguments treated in thisway are the argument to the ps request, the third argument to the cs request, the second and 
fourth arguments to thetkf request, the argument to the\H escape sequence, and those variants of the \s escape sequence 
that take a numeric expression as their argument. 

For example, suppose sizescale is 1,000; then ascaled point will be equivalent to a millipoint; the request .ps 10.25 is 
equivalent to .ps 10.25Z, and so sfltsthe point size to 10,250 scaled points, which is equal to 10.25 points. 

The number register \n(.s returns the point size in points as decimal fraction. There is also anew numberregister\ni.ps] 
that returns the point size in scaled points 

It would make no sense to use the z scale indicator in a numeric expression whose default scale indicator was neither u nor z, 
and so troff disallows this. Similarly, it would make no sense to use a scaling indicator other than z or u in a numeric 
expression whose default scale indicator was z, and so troff disallows thisas well. 

There isalso new scale indicator s that multiplies by the number of units in ascaled point. So, for example, \n[.ps]s isequal 
to im. Be sure not to confuse the s and z scale indicators. 

NUMERIC EXPRESSIONS 

Spaces are permitted in a number expression within parentheses. 
m indicates a scale of hundredths of an em. 
e 1 >?e2 The maximum of ei and e2. 

e 1 <?e2 The minimum of ei and e2. 

(c;e) Evaluate e using c as the default scaling indicator. If c is missing, ignore scaling indicators in the evaluation 

Of e. 


NEW ESCAPE SEQUENCES 

\A'a nyt hi ng 1 This expands to i or 0 according to whether any t hi ng is or is not acceptable as the name of a string, 

macro, diversion, number register, environment, or font. It will return 0 if a nyt hi ng is empty. This 
is useful if you want to look up user input in some sort of associative table 
\c 1 x x x 1 Typeset character named x*x. N ormally it is more convenient to use \[xxx]. But \c has the 

advantage that it is compatible with recent versionsof UN IX and isavailablein compatibility 
mode 

\e This is equivalent to an escape character, but it's not interpreted in copy mode. For example 

strings to start and end superscripting could be defined like this: 

.ds { \v '- ,3m ' \s '\En[ .s]*6u/10u ' 

.ds { \s0\v 1 .3m 1 


The use of \e ensures that these definitions will work even if \*f gets interpreted in copy-mode (for example by being used 
in a macro argument). 


\R'namen' 


\s[n], \s'n 1 
\Vx\ V(xx \ V[xxx ] 


Typeset the character with coden in the current font, n can beany integer. M ost devices only have 
characters with codes between 0 and 255. If the current font does not contain a character with that 
code, special fonts will not be searched. The \n escape sequence can be conveniently used on 
conjunction with the char request: 

.char \[phone] \f(ZDnN'37 1 

The code of each character is given in the fourth column in the font description file after the 
charset command. It is possible to include unnamed charactersin the font description file by using 
a name of the \n escape sequence is the only way to use these. 

This has thesame effect as .nrnamen 

Set the point sizeto nn points; nn must be exactly two digits. 

Set the point sizeto n scaled points; n is a numeric expression with a default scale indicator of z. 
Interpolatethecontentsoftheenvironmentvariablexxx, as returned bygetenv(3). \v is interpreted 
in copy-mode. 
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This is approximately equivalent to \x'\*[xxx ] ■. H owever, the contents of the string or macro xxx 
are not interpreted; also, it ispermitted for xxx to have been defined as a macro and thus contain 
newlines (it is not permitted for the argument to \x to contain newlines). The inclusion of newlines 
requires an extension to the U N IX troff output format and will confuse drivers that do not know 
about thisextension. 

Print anything and then restore the horizontal and vertical position; a nyt hi ng may not contain tabs 
or leaders 

The name by which the current macro wasinvoked. Theais request can makeamacro have more 
than one name 

I n a macro, the concatenation of all the arguments separated by spaces 

In a macro, the concatenation of all the arguments with each surrounded by double quotes and 

separated by spaces. 

In a macro, this gives the mi th ornnnth argument. M acroscan have an unlimited number of 
arguments. 

When used in a diversion, this will transparently embed a nyt hi ng in thediversion. anyth i ng isread 
in copy mode. W hen the diversion is reread, a nyt hi ng will be interpreted, any t hi ng may not contain 
newlines; useu if you want to embed newlines in a diversion. The escape sequence\? isalso 
recognized in copy mode and turned into a single internal code; it isthiscodethat terminates 

anythi ng.ThUS 



will print 4. 

\/ This increases the width of the preceding character so that the spacing between that character and 

thefollowing character will be correct if the following character is a Roman character. For example, 
if an italic f is immediately followed by a Roman right parenthesis, then in many fonts the top right 
portion of the f will overlap the top left of the right parenthesis, producing/), which is ugly. 
Inserting \/ produces and avoids this problem. It is a good idea to use this escape sequence 
whenever an italic character is immediately followed by a Roman character without any intervening 
space. 

\, This modifies the spacing of thefollowing character so that the spacing between that character and 

the preceding character will correct if the preceding character is a Roman character. For example, 
inserting \, between the parenthesis and the f changes to (f. It is a good idea to use this escape 
sequence whenever a Roman character is immediately followed by an italic character without any 
intervening space. 

\) Like \& except that it behaves like a character declared with the cfiags request to be transparent for 

the purposes of end-of-sentence recognition. 

r This produces an unbreakable space that stretches likea normal interword space when a line is 

adjusted. 

\# Everything up to and including the next newline is ignored. This is interpreted in copy mode. This 

is like \% except that \% does not ignore theterminating newline. 





Create an alias xx for number register object named yy. The new name and the old name will be 
exactly equivalent. If yy is undefined, a warning of type reg will be generated, and the request will 
be ignored. 

Create an aliasxx for request, string, macro, or diversion object named yy. The new name and the 
old name will be exactly equivalent (it issimilar to a hard rather than a soft link). If yy is unde¬ 
fined, a warning of type mao will be generated, and the request will be ignored. Thede, am, di, da, 
ds, and as requests only create a new object if the name of the macro, diversion, or string diversion 
is currently undefined or if it is defined to be a request; normally, they modify the value of an 
existing object. 

This request only exists in order to make it possible to make certain gross hacks work with GNU 
troft. It unformats thediversion xx in such away that ASCII characters that wereformatted and 
diverted into xx will be treated like ordinary input characters when xx isreread. For example this: 


@nr\n\1 

.br 

.tr @@ 
.asciify x 


will set register n to i. 

Print a backtrace of the input stack on stderr. 

Break out of a while loop. See also the while and continue requests Be sure not to confuse this with 
the br request. 

C haracters c 1 , c 2 , ... have properties determined by n, which is ORed from the following. 

The character ends sentences (Initially, characters.?! have this property.) 

Lines can be broken before the character (initially, no characters have this property); a line will not 
be broken at a character with this property unless the characters on each side both have nonzero 
hyphenation codes 

Lines can be broken after the character (initially, characters -\(hy\(em havethis property); aline 
will not be broken at a character with th i s property unless the characterson each side both have 
nonzero hyphenation codes 

Thecharacter overlaps horizontally (initially, characters \(ui\(rn\(ru havethis property). 

The character overlaps vertically (initially, character \ (br has this property). 

An end-of-sentence character followed by any number of characters with this property will be 
treated as the end of a sentence if followed by a newline or two spaces; in other words thecharacter 
is transparent for the purposes of end-of-sentence recognition; this is the same as having a zero 
spacefactorinTeX (initially, characters ')]*\(dg\(rq havethis property). 

Define character c to bestri ng. Every time character c needs to be printed, string will be processed 
in a temporary environment and the result will be wrapped up into a single object. Compatibility 
mode will be turned off and the escape character will beset to \ whilest r i ng is being processed. 
Any emboldening, constant spacing, or track kerning will be applied to thisobject rather than to 
individual characters in stri ng. A character defined by this request can be used just like a normal 
character provided by the output device I n particular, other characters can be translated to it with 
the tr request; it can be made the leader character by the ic request; repeated patterns can be drawn 
with thecharacter by using the \i and \l escape sequences; wordscontaining the character can be 
hyphenated correctly, if the hcode request is used to give the character a hyphenation code. There is 
a special antirecursion feature Use of character within the character's definition will be handled 
like normal characters not defined with char. A character definition can be removed with the rchar 
request. 
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.hcodeclc o d e1c2c o d e 2.. 


.hlal a n g 


.hpffiI e 




.opens t r ea mf i I e na me 


C hop the last character off macro, string, or diversion * *. This is useful for removing the newline 
from the end of diversionsthat are to be interpolated as strings. 

Close the stream named stream; stream will no longer bean acceptable argument to thewrite 
request. See the open request. 

Finish the current iteration of awhile loop. See also thewhiie and break requests 
If n is nonzero or missing, enable compatibility mode; otherwise, disable it. In compatibility mode, 
long names are not recognized, and the incompatibilities caused by long names do not arise. 
Interpret. xxx with compatibility mode disabled. For example, .do fam t would have the same 
effect as. t am t except that it would work even if compatibility mode had been enabled. Note that 
the previous compatibility mode is restored before any files sourced by xxx are interpreted. 

Set the current font fami ly to x x . T he current font fami ly is part of the current en vi ronment. See 
the description of the sty request for more information on font families. 

When the current font is f , fonts s 1, s 2 , ... will be special; that is, they will searched for 
characters not in the current font. Any fonts specified in the special request will be searched after 
fonts specified in the f special request. 

T ranslate font f to g. Whenever a font named f is referred to in \f escape sequence, or in the ft, 
ui, bd, cs, tkf, special, fspeciai, fp, or sty requests, font g will be used. If g is missing, or equal to 
f , then font f will not be translated. 

Set the hyphenation codeof character ci tocodei and that of c 2 to c 0 d e 2 . A hyphenation code must 
be a single input character (not a special character) other than a digit or a space. Initially, each 
lowercase letter has a hyphenation code, which is itself, and each uppercase letter has a hyphenation 
code which is the lowercase version of itself. See also thehpf request. 

Set the current hyphenation language to 1 an g. FI yphenation exceptions specified with the hw 
request and hyphenation patterns specified with thehpf request are both associated with the 
current hyphenation language. T he hia request is usually invoked bythetroffrc file. 

Set the maximum number of consecutive hyphenated lines to n. If n is negative there is no 
maximum. T he default value is -1. T his value is associated with the current environment. 0 nly 
lines output from an environment count towards the maximum associated with that environment. 

FI yphens resulting from \% are counted; explicit hyphens are not. 

Read hyphenation patternsfrom file; this will be searched for in the same way that tmac. name is 
searched for when the-mname option isspecified. It should have the same format as the argument to 
the\patterns primitive in TeX; the lettersappearing in thisfile are interpreted as hyphenation 
codes A % character in the patterns file introduces a comment that continues to the end of the line. 
The set of hyphenation patterns is associated with the current language set by the hia request. The 
hpf request is usually invoked by the troff rc file 

Set the hyphenati on margin to n : when the current adjustment mode is not b, the line will not be 
hyphenated if the line is no more than n short. The default hyphenation margin iso. The default 
scaling indicator for this request is m. The hyphenation margin is associated with the current 
environment. The current hyphenation margin is available in the \n[.hym] register. 

Set the hyphenati on space to n : when the current adjustment mode is b, don't hyphenate the line if 
the line can be justified by adding no more than n extra space to each word space The default 
hyphenation space iso. The default scaling indicator for this request ism. The hyphenation space is 
associated with the current environment. The current hyphenation space is available in the 
\n[.hys] register. 

If n is nonzero or missing, enable pairwise kerning; otherwise, disable it. 

The same as the so request except that f 1 e is searched for in the same way that tmac. name is 
searched for when the-mname option isspecified. 

M akethen built-in condition true and the t built-in condition false Thiscan be reversed using 
the troff request. 

Open f i 1 ename for writing and associate the stream named stream with it. See also the close and 
write requests. 
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openast r eamf i I ename 


Ptr 




specialsls2... 


Like open, but if f i i ename exists, append to it instead of truncating it. 

Print the names and contents of all currently defined number registers on stderr. 

This behaves like the so request except that input comes from the standard output of command. 

Print the names and positions of all traps (not including input line traps and diversion traps) on 
stderr. Empty slotsin the page trap list are printed as well, because they can affect the priority of 
subsequently planted traps. 

Remove the definitionsof charactersc 1, c 2, ... This undoes theeffect of a char request. 

Right justify the next n input lines. Without an argument, right justify the next input line. The 
number of lines to be right justified is available in the \n[. r j ] register. This implicitly does .ceo. 
Thece request implicitly does .rjo. 

Rename number register** toyy. 

Set the soft hyphen character to c. If c is omitted, the soft hyphen character will beset to the 
default \<hy. The soft hyphen character is the character that will be inserted when a word is 
hyphenated at a line break. If the soft hyphen character does not exist in the font of the character 
immediately preceding a potential break point, then the line will not be broken at that point. 

N either definitions (specified with the char request) nor translations (specified with the tr request) 
are considered when finding the soft hyphen character. 

In a macro, shift the arguments by n positions argument i becomes argument i -n; arguments 1 to n 
will no longer be available. If n is missing, arguments will be shifted by 1. Shifting by negative 
amounts is currently undefined. 

Fontss 1, s 2 are special and will be searched for characters not in the current font. 

Associate style f with font position n. A font position can be associated either with a font or with a 
style. The current font is the index of a font position and so is also either a font or a style. When it 
isa style, thefont that is actually used isthefont the name of which isthe concatenation of the 
name of the current family and the name of the current style. For example if the current font is 1 
and font position 1 is associated with style Rand the current font family is t, then fontTR will be 
used. If the current font is not a style, then the current family is ignored. When the requests cs, bd, 
tkf, uf, or t special are applied to a style, then they will instead be applied to the member of the 
current family corresponding to that style. The default family can be set with the-f option. The 
styles command in the desc file controls which font positions (if any) are initially associated with 
styles rather than fonts. 

Enable track kerning for font f. When the current font isf, the width of every character will be 
increased by an amount between ni and n2; when the current point size is less than or equal to si, 
the width will be increased by m; when it isgreaterthan or equal to s 2, the width will be increased 
by m; when the point size is greater than or equal to si and less than or equal to s 2, theincreasein 
width isa linear function of the point size 

T ransparently output the contents of file f i 1 ename. Each line is output as it would be were it 
preceded by \i; however, the lines are not subject to copy-mode interpretation. If thefiledoesnot 
end with a newline, then a newline will be added. For example, you can definea macro* 
containing thecontents of filet, using 


Unlike with thecf request, the file cannot contain characters such as nul that are not legal troff 
input characters. 

t rnt abed T his is the same as the t r request except that the translations do not apply to text that is transpar¬ 

ently throughput into a diversion with \l. For example, 
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.troff 


.whilecanyt hi ng 


.writestreamanyt hing 


will print b; if trnt is used instead of tr, it will print a. 

M akethe n built-in condition false and the t built-in condition true. This undoes the effect of the 
nroff request. 

Enable vertical position traps if n is nonzero, disable them otherwise. Vertical position traps are 
traps set by the wh or at requests. T raps set by the it request are not vertical position traps T he 
parameter that controls whether vertical position traps are enabled is global. I nitially, vertical 
position traps are enabled. 

Control warnings, n isthesum of the numbers associated with each warning that isto be enabled; 
all other warnings will be disabled. The number associated with each warning is listed in the 
"Warnings" subsection. For example .warn 0 will disable all warnings, and .warn 1 will disable all 
warnings except that about missing characters If n is not given, all warnings will be enabled. 

While condition c istrue, accept a n y t h i ng as input; c can beany condition acceptable to an if 
request; anythi ng can comprise multiple lines if thefirst linestarts with \{ and the last line ends 
with \>. See also the break and continue requests. 

W rite anythi n g to the stream named st ream, stream must previously have been the subject of an 
open request, anythi ng is read in copy mode; a leading will be stripped. 


EXTENDED REQUESTS 

.off i 1 ename When used in a diversion, this will embed in thediversion an object which, when reread, will cause 

the contents off i 1 ename to be transparently copied through to the output. In U NIX troff, the 
contents of f i 1 ena me are immediately copied through to the output regardless of whether there is a 
current diversion; this behavior is so anomalous that it must be considered a bug. 

.evxx If xx is not a number, this will switch to a named environment called xx. The environment should 

be popped with a matching ev request without any arguments, just as for numbered environments 
There is no limit on the number of named environments; they will be created thefirst time that 
they are referenced. 

.fpnfif 2 Thefp request has an optional third argument. This argument gives the external name of the font, 

which is used for finding the font description file The second argument gives the internal name of 
the font, which is used to refer to the font in troff after it has been mounted. If there is no third 
argument, then the internal name will be used as the external name. T hisfeature allows you to use 
fonts with long names in compatibility mode 

. ssmn When two arguments are given to thess request, the second argument gives thesentence space size. 

If the second argument is not given, the sentence space size will be the same as the word space size. 
Liketheword spacesizey the sentence space is in unitsof one twelfth of the spacewidth parameter 
for the current font. I nitially, both the word space size and the sentence space size are 12. T he 
sentence space size is used in two circumstances: If the end of a sentence occurs at the end of aline 
in fill mode then both an interword space and a sentence space will be added; if two spaces follow 
the end of a sentence in the middle of aline, then the second space will be a sentence space. N ote 
that the behavior of UN IX troff will be exactly that exhibited by GN U troff if a second argument 
is never given to thess request. In GN U troff, as in UN IX troff, you should always follow a 
sentence with either a newline or two spaces. 

.tan in 2.. .nnTr i r2... rn Set tabs at positions n i, n2,...,nn and then set tabs at nn +r i, n n +r 2,...., nn+rn and then at 

nn+rn+ri, nn+r n+r 2,..., nn+r n+r n, and so on. For example .ta t .51 will s€t tabs every half an 
inch. 
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\n[.fam] The current font family. This isa string-valued register. 

\n[.tp] The number of the next free font position. 

\n[.g] Always i. M acros should use this to determine whether they are running under GN U troff. 

\n[. hia] The current hyphenation language as set by the hia request. 

\n[. hio] Thenumberof immediately preceding consecutive hyphenated lines 

\n[. him] The maximum allowed number of consecutive hyphenated lines, asset by the him request. 

\n[.hy] Thecurrent hyphenation flags (asset by the hy request.) 

\n[. hym] The current hyphenation margin (as set by the hym request.) 

\n[. hys] Thecurrent hyphenation space (asset by the hys request.) 

\n[. in] The indent that applies to the current output line. 

\n[. kern] i if pairwise kerning is enabled, 0 otherwise. 

\n[.ig] Thecurrent Iigature mode (asset by the lg request.) 

\n[ .li] The line length thatappliesto thecurrent output line. 

\n[. it] The title length as set by the it request. 

\n[. ne] T he amount of space that was needed in the last ne request that caused a trap to be sprung. Useful in 

conjunction with the \n[ .trunc] register. 

\n[. pn] T he number of the next page either the value set by a pn request, or the number of the current page 

plus 1. 

\n[.ps] Thecurrent pointsizein scaled points 

\n[.psr] The last requested pointsize in scaled points 

\n[.rj] Thenumberof linesto be right-justified asset by therj request. 

\n[.sr] The last requested pointsize in points as a decimal fraction. This is a string-valued register. 

\n[ .tabs] A string representation of thecurrent tab settings suitable for use as an argument to theta request. 

\n[.trunc] T he amount of vertical space truncated by the most recently sprung vertical position trap, or, if thetrap 

wassprung by an ne request, minus the amount of vertical motion produced by thene request. In other 
words, at the point a trap is sprung, it represents the difference of what the vertical position would have 
been but for the trap, and what the vertical position actually is Useful in conjunction with the\n[ .ne] 
register. 

\ n [. ss ] T hese give the values of the parameters set by the fi rst and second arguments of the ss request. 

\n[.sss] 

\n[.vpt] 1 if vertical position traps are enabled, 0 otherwise 

\n[ .warn] Thesum of the numbers associated with each of the currently enabled warnings. The number associated 
with each warning is listed in the "Warnings" subsection. 

\n(.x The major version number. For example, if the version number is 1.03 then \n(.x will contain 1. 

\n(.y The minor version number. For example, if the version number is 1.03 then \n(.y will contain 03. 
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Thefollowing registers are set by the \w escape sequence: 

\n[rst] 

\n[ rsb] Like the st and sb registers, but takes account of the heightsand depths of characters. 

\n[ssc] The amount of horizontal space (possibly negative) that should be added to the last character before a 

subscript. 

\n[skw] How far to right of the center of the last character in the\w argument, the center of an accent from a 

roman font should be placed over that character. 

Thefollowing read/write number registers are available: 

\n[systat] The return value of the system o function executed by the last sy request. 

\n[siimit] If greater than 0, the maximum number of objects on the input stack. If less than or equal to 0, there is no 
limit on the number of objects on the input stack. With no limit, recursion can continue until virtual 
memory is exhausted. 

MISCELLANEOUS 

Fonts not listed in theDEsc file are automatically mounted on the next available font position when they are referenced. 

If a font is to demounted explicitly with thefp request on an unused font position, it should be mounted on the first unused 

font position, which can be found in the\n[ .fp] register; although troff does not enforce this strictly, it will not allow a font 

to be mounted at a position whosenumber ismuch greater than that of any currently used position. 

Interpolating a string does not hide existing macro arguments Thus in a macro, a more efficient way of doing 


is 


If the font description file contains pairwise kerning information, characters from that font will be kerned. Kerning between 
two characters can be inhibited by placing a \& between them. 

In a string comparison in a condition, characters that appear at different input levels to thefirst delimiter character will not 
be recognized asthesecond or third delimiters. Thisappliesalso to theti request. I n a \w escape sequence, a character that 
appears at a different input level to the starting delimiter character will not be recognized as the closing delimiter character. 

W hen decoding a macro argument that isdelimited by double quotes, a character that appears at a different input level to 
the starting delimiter character will not be recognized as the closing delimiter character. The implementation of \$@ ensures 
that the double quotes surrounding an argument will appear the same input level, which will be different to the i nput level 
of the argument itself. In a long escape name ] will not be recognized as a closing delimiter except when it occurs at the same 
input level as the opening ]. In compatibility mode no attention is paid to the input level. 

T here are some new types of condition: 

.ifrxu T rue if there is a number register named xxx. 

. ifdx xx T rue if there is a string, macro, diversion, or request named xxx. 

. ifcch T rue if there is a character c h available; ch is either an ASCII character or a special character\(xx or\[xxx];the 

condition will also be true if ch has been defined by the char request. 


WARNINGS 

The warnings that can be given by troff are divided into thefollowing categories. The name associated with each warning is 
used by the-wand -w options; the number is used by thewarn request, and by the .warn register, 
chan N onexistent characters. Thisisenabled by default. 

number2 Invalid numeric expressions. Thisisenabled by default. 

break4 In fill mode, lines which could not be broken so that their length was less than the line length. This is 

enabled by default. 

deiim8 M issing or mismatched closing delimiters 
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eii6 Use of the ei request with no matching ie request. 

scaie32 M eaninglessscaling indicators. 

nange64 0 ut of range arguments 

syntaxes D ubious syntax in numeric expressions. 

di256 U se of di or da without an argument when there is no current diversion. 

mac5i2 Use of undefined strings, macros and diversions When an undefined string, macro, or diversion isused, 

that string ^automatically defined as empty. So, in most cases, at most one warning will be given for each 
name 

regi024 Useof undefined number registers When an undefined number register isused, that register ^automati¬ 

cally defined to have a value of 0. A definition is automatically made with a value of 0. So, in most cases, at 
most one warning will be given for use of a particular name. 

tab2048 Inappropriate use of a tab character. Either use of a tab character where a number was expected, or use of 

tab character in an unquoted macro argument, 
right -brace4096 U se of \g where a number was expected. 
missing8i92 Requests that are missing nonoptional arguments. 

inputi6384 Illegal input characters. 

escape32768 Unrecognized escape sequences. W hen an unrecognized escape sequence is encountered, the escape 
character is ignored. 

space65536 M issing space between a request or macro and its argument. This warning will be given when an 

undefined name longer than two characters is encountered, and thefirst two characters of the name make 
a defined name. The request or macro will not be invoked. W hen this warning isgiven, no macro is 
automatically defined. This isenabled by default. Thiswarningwill never occur in compatibility mode. 
fonti3i072 N onexistent fonts This isenabled by default. 

ig262i44 Illegal escapes in text ignored with the ig request. These are conditions that are errors when they do not 

occur in ignored text. 

T here are also names that can be used to refer to groups of warnings: 

an All warnings except di, mac, and reg. It is intended that this covers all warnings that are useful with 

traditional macro packages, 
w All warnings 


INCOMPATIBILITIES 

Long names cause some incompatibilities UN IX troff will interpret 

.dsabcd 

as defining a string ab with contents cd. Normally, GNU troff will interpret thisasa call of a macro named dsabcd. Also 
UNIX troff will interpret \*[ or\n[ as references to a string or number register called [. In GNU troff, however, this will 
normally be interpreted as the start of a long name In compatibility modeGN U troff will interpret these things in the 
traditional way. In compatibility mode however, long names are not recognized. Compatibility mode can be turned on with 
the-c command-line option, and turned on or off with thecp request. The number register \n(.c isi if compatibility mode 
is on, 0 otherwise. 

GNU troff does not allow the use of the escape sequences in names of strings macros diversions number registers fonts, or 
environments; UN IX troff does. The\A escape sequence may be helpful in avoiding useof these escape sequences in names 
Fractional point sizes cause one noteworthy incompatibility. In U NIX troff theps request ignores scale indicators and so 

.ps 10U 

will set the pointsize to 10 points whereas in GNU troff it will sdt the pointsize to 10 scaled points 
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I n G N U troff there is a fundamental difference between unformatted, input characters, and formatted, output characters. 
Everything that affects how an output character will be output is stored with the character; after an output character has been 
constructed, it is unaffected by any subsequent requests that are executed, including bd, cs, tkf, tr, orfp requests. Normally 
output characters are constructed from input characters at the moment immediately before the character is added to the 
current output line. M acros, diversions, and strings are all, in fact, thesametypeof object; they contain lists of input 
characters and output characters in any combination. An output character does not behave like an input character for the 
purposes of macro processing; it does not inherit any of the special properties that the input character from which it was 
constructed might have had. For example this: 

\\\\ 


will print \\ in GN U troff; each pair of input \sisturned into one output \ and the resulting output \s are not interpreted 
asescape characters when they are reread. UN IX troff would interpret them as escape characters when they were reread and 
would end up printing one\.T hecorrect way to obtain a printable \ is to use the \e escape sequence: this will always print a 
single instance of thecurrent escape character, regardless of whether or not it is used in a diversion; it will also work in both 
GNU troff and UN IX troff. If you wish for some reason to store in a diversion an escape sequence that will be interpreted 
when the diversion is reread, you can either use the traditional \ \ transparent output facility, or, if this is unsuitable, the new 
\? escape sequence. 

ENVIRONMENT 

groff_tmac_path A colon-separated list of directories in which to search for macro files 

groff_typesetter D efault device 

groff_font_path A colon-separated list of directories in which to search forthedevname directory, troff will search 

in directories given in the-F option before these, and in standard directories (:/usr/itb/groff /font, 
: /usr/nb/font, and : /usr/itb/font) after these. 


FILES 

/usr/lib/groff/font/devname/DESC 
/usr/lib/groff/tmac/troffrc 
/usr/lib/groff/tmac/tmac.name 
/usr/lib/groff/font/devname/DESC 
/usr/lib/groff/font/devname/F 


Initialization file 
M aero files 

Device description file for device name 
Font file for font F of device name 


SEE ALSO 

groff(l) gtbl(l), gpic(l), geqn(l), grops(l), grodvi(l), grotty(l), groff_font(5), groff_out(5), groff_char(7) 

GroffVerson 1.09,14 February 1994 


gzip, gunzip, zcatgzip, gunzip, zcat 

gzip, gunzip, zcatgzip, gunzip, zcat— Compressor expand files 

SYNOPSIS 

gzip [ -acdfhlLnNrtvV19 ][-Ssuffix] [ name ... ] 
gunzip [ -acfhlLnNrtvV ][-Ssuffix] [ name ... ] 




gzip, gunzip, zcatgzip, gunzip, zcat 


DESCRIPTION 

gzip reduces the size of the named files using Lempel-Ziv coding (LZ77). W henever possible, each file is replaced by one 
with the extension .gz, while keeping the same ownership modes, access, and modification times. (The default extension is 
-gz for V M S, z for M S-DOS, OS/2 FAT, WindowsNT FAT and Atari.) If no files are specified, or if a filename is-, the 
standard input is compressed to the standard output, gzip will only attempt to compress regular files In particular, it will 
ignore symbolic links. 

If the compressed filename istoo long for its filesystem, gzip truncates it. gzip attempts to truncate only theparts of the 
filename longer than three characters. (A part is delimited by dots.) If the name consists of small parts only, the longest parts 
are truncated. For example, if filenames are limited to 14 characters, gzip.msdos.exe iscompressed to gzi.msd.exe.gz. N ames 
are not truncated on systems that do not have a limit on filename length. 

By default, gzip keeps the original filename and timestamp in the compressed file These are used when decompressing the 
file with the-N option. This is useful when the compressed filename wastruncated or when the time stamp was not preserved 
after a file transfer. 

Compressed files can be restored to their original form using gzip -d or gunzip or zcat. If the original name saved in the 
compressed file is not suitable for its filesystem, a new name is constructed from the original one to make it legal, 
gunzip takes a list of files on its command line and replaces each file whose name ends with .gz, -gz, .z, -z, z, or .z and which 
begins with the correct magic number with an uncompressed file without the original extension, gunzip also recognizes the 
special extensions .tgz and .taz as shorthands for .tar.gz and .tar.z respectively. W hen compressing, gzip uses the .tgz 
extension if necessary instead of truncating a file with a .tar extension. 

gunzip can currently decompress files created by gzip, zip, compress, compress -h, or pack. The detection of the input format 
is automatic. When using the first two formats, gunzip checks a 32-bit CRC. For pack, gunzip checks the uncompressed 
length. The standard compress format was not designed to allow consistency checks FI owever, gunzip is sometimes able to 
detect a bad .z file If you get an error when uncompressing a .z file do not assume that the .z file iscorrect simply because 
the standard uncompress does not complain. Thisgenerally means that the standard uncompress does not check its input, and 
happily generates garbage output. The SCO compress -h format (izh compression method) does not include a CRC but also 
allows some consistency checks 

Files created by zip can be uncompressed by gzip only if they have a single member compressed with the deflation method. 
Thisfeature isonly intended to help conversion oftar.zip files to the tar.gz format. To extract zip fileswith several 
members use unzip instead of gunzip. 

zcat is identical to gunzip -c. (0 n some systems, zcat may be installed asgzcat to preserve the original link to compress.) 
zcat uncompresses either a list of files on the command line or its standard input and writes the uncompressed data on 
standard output, zcat will uncompress files that have the correct magic number whether they have a .gz suffix or not. 
gzip uses theLempel-Ziv algorithm used in zip and pkzip. The amount of compression obtained depends on the size of the 
input and the distribution of common substrings Typically, text such as source code or English is reduced by 60 to 70 
percent. Compression is generally much better than that achieved by LZW (as used in compress), FI uffman coding (as used 
in pack), or adaptive FI uffman coding (compact). 

Compression is always performed, even if the compressed file is slightly larger than the original. The worst case expansion isa 
few bytesfor the gzip file header, plus 5 bytes every 32 KB block, or an expansion ratio of 0.015 percent for large files. Note 
that theactual number of used disk blocks almost never increases gzip preserves the mode ownership, and timestamps of 
files when compressing or decompressing. 

OPTIONS 

-a -ascii ASCII text mode: convert end-of-linesusing local conventions. Thisoption issupported 

only on some non-U NIX systems. For M S-D 0 S, cr lf isconverted to lf when compress¬ 
ing, and lf isconverted to cr lf when decompressing. 

-c -stdout -to-stdout Write output on standard output; keep original files unchanged. If there are several input 

files, the output consists of a sequence of independently compressed members T o obtain 
better compression, concatenate all input files before compressing them. 
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D ecompress. 

Force compression or decompression even if thefile has multiple linksor the corresponding 
file already exists, or if the compressed data is read from or written to a terminal. If the 
input data is not in a format recognized by gzip, and if the option -stdout is also given, 
copy the input data without change to thestandard output; let zcat behave as cat. If -f is 
not given, and when not running in the background, gztp prompts to verify whether an 
existing file should be overwritten. 

D isplay a help screen and quit. 

For each compressed file, list the following fields compressed size (size of the compressed 
file), uncompressed size (size of the uncompressed file), ratio (compression ratio-0.0% if 
unknown), uncompressed name (nameof the uncompressed file). The uncompressed size is 
given as -i for files not in gztp format, such as compressed .z files. To get the uncompressed 
sizefor such a file, you can use: 
zcat file.Z | wc -c 

In combination with the-verbose option, thefollowing fields are also displayed; method 
(compression method), crc (the 32-bit CRC of the uncompressed data), date & time 
(timestamp for the uncompressed file). The compression methods currently supported are 
deflate, compress, lzh (SCO compress -h) and pack. Thecrc isgiven aSffffffff for a file 
notin gzip format. 

With -name, the uncompressed name date and time are those stored within the compressed 
file if present. 

W ith -verbose, the size totals and compression ratio for all files is also displayed, unless 
some sizes are unknown. W ith -quiet, the title and totals lines are not displayed. 

D isplay the gzip license and quit. 

When compressing, do not save the original filename and timestamp by default. (The 
original name is always saved if the name had to be truncated.) When decompressing, do 
not restore the original filename if present (remove only the gzip suffix from the compressed 
filename) and do not restore the original timestamp if present (copy it from the compressed 
file). Thisoption isthedefault when decompressing. 

When compressing, always save the original filename and timestamp; this is the default. 
When decompressing, restore the original filename and timestamp if present. Thisoption is 
useful on systems that have a limit on filename length or when the timestamp has been lost 
after a file transfer. 

Suppress all warnings. 

T ravel the directory structure recursively. If any of the filenames specified on the command 
lineare directories, gzip will descend into the directory and compressall thefiles it finds 
there (or decompress them i n the case of gunzip). 

Use suffix .suf instead of .gz. Any suffixcan be given, but suffixes other than .z and .gz 
should be avoided to avoid confusion when files are transferred to other systems A null 
suffix forces gunzip to try decompression on all given files regardless of suffix, as in the 
following: 

gunzip -S "" * (*.* for M S-DOS) 

Previous versionsof gzip used the .z suffix. This was changed to avoid a conflict with 

pack(l). 

T est. C heck the compressed fi le i ntegri ty. 

Verbose. Display the name and percentage reduction for each file compressed or decom¬ 
pressed. 

Version. Display the version number and compilation options, then quit. 

Regulate the speed of compression using the specified digit#, where-i or - -fast indicates 
thefastest compression method (lesscompression) and -9 or - -best indicatestheslowest 
compression method (best compression). The default compression level is -6 (that is, biased 
towards high compression at expense of speed). 
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ADVANCED USAGE 

M ultiple compressed files can be concatenated. In this case, gunzip will extract all members at once For example, 

gzip -c filel >foo.gz gzip -c file2>» foo.gz 

Then 

gunzip -c too 

is equivalent to 

cat filel file2 

In case of damage to one member of a .gz file, other members can still be recovered (if the damaged member is removed). 

H owever, you can get better compression by compressing all members at once. 

cat filel file2 | gzip > foo.gz 

compresses better than 

gzip -c filel file2 >foo.gz 

If you want to recompress concatenated files to get better compression, use 

gzip -cd old.gz ] gzip > new.gz 

If a compressed file consists of several members, the uncompressed sizeandCRC reported bythe-nst option applies to the 
last member only. If you need the uncompressed size for all members, you can use 

gzip -cd file.gz j wc -c 

If you wish to create a single archive file with multiple members so that members can later be extracted independently, use an 
archiver such as tar or zip. GNU tar supports the -z option to invoke gzip transparently, gzip is designed as a complement 
to tar, not as a replacement. 

ENVIRONMENT 

The environment variable gzip can hold a set of default options for gzip. These options are interpreted first and can be 
overwritten by explicit command-line parameters For example 

For sh: GZIP="-8v -name" 

Export GZIP for cshlsetenv GZIP "-8v -name" 

For M S-DOS: set GZIP=-8v -name 

On Vax/VM S, the name of the environment variable is gzip_opt, to avoid a conflict with the symbol set for invocation of the 
program. 

SEE ALSO 

znew(l), zcmp(l), zmore(l), zforce(l), gzexe(l), zip(l), unzip(l), compress(l), pack(l), compact(l) 

DIAGNOSTICS 

Exit status isnormally 0; if an error occurs, exit status is 1. If a warning occurs, exit status is 2. 

Usage gzip [-cdfhlLnNrtvV19] [-S suffix] [file ...] 

Invalid options were specified on the command line. 

file: not in gzip format 

Thefile specified to gunzip has not been compressed, 
file: Corrupt input. Use zcat to recover some data. 

The compressed file has been damaged.The data up to the point of failure can be recovered using 


zcat file > recover 
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file: compressed with x* bits, can only handle yy bits 

file was compressed (using LZW) by a program that could deal with more bits than the decompress code on this machine 
Recompress thefile with gzip, which compresses better and uses less memory, 
file: already has .gz suffix--no change 

Thefile is assumed to be already compressed. Rename thefile and try again. 

file already exists; do you wish to overwrite (y or n)? 

Respond y if you want the output file to be replaced; n if not. 

gunzip: corrupt input 

A SIGSEGV violation was detected, which usually meansthat the input file has been corrupted. 


Percentage of the input saved by compression. (Relevant only for-v and -I.) 

- not a regular file or directory: ignored 

W hen the input file is not a regular file or directory, (such as a symbolic link, socket, FIFO, device file), it is left unaltered. 

- has xx other links: unchanged 

The input file has links; it is left unchanged. See ln(l) for more information. 

Use the -f flag to force compression of files that are multiply linked. 

CAVEATS 

W hen writing compressed data to a tape it is generally necessary to pad the output with zeroes up to a block boundary. 

W hen the data is read and the whole block is passed to gunzip for decompression, gunzip detects that there is extra trailing 
garbage after the compressed data and emits a warning by default. You have to use the -quiet option to suppress the 
warning. Thisoption can beset in theGzip environment variable asin thefollowing: 

for sh: GZIP="-q" tar -xfz -block-compress /dev/rst0 for csh: 

(setenv GZIP -q; tar -xfz -block-compr /dev/rst0 

In the preceding example, gzip isinvoked implicitly by the -z option of GN U tar. M ake sure that the same block size (b 
option of tar) is used for reading and writing compressed data on tapes (T his example assumes you are using the G N U 
version of tar.) 

BUGS 

The -list option reports incorrect sizes if they exceed two gigabytes. The -list option reports sizes as-i and ore asffffffff 
if the compressed fi le is on a nonseekable medi a. 

In some rare cases the-best option gives worse compression than the default compression level (-6). On some highly 
redundant files compress compresses better than gzip. 

Local 


gzexe 

gzexe— Compress executable files in place 

SYNOPSIS 


gzexe [ name ... ] 
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DESCRIPTION 

Thegzexe utility enables you to compress executables in place and have them automatically uncompress and execute when 
you run them (at a penalty in performance). For example if you execute gzexe /bin/cat, it will create the following two files: 

-r-xr-xr-x 1 root bin 9644 Feb 11 11:16 /bin/cat 
-r-xr-xr-x 1 bin bin 24576 Nov 23 13:21 /bin/cat' 

/bin/cat' isthe original file and /bin/cat isthe self-uncompressing executable file You can remove/bin/cat' when you are 
sure that /bin/cat works properly. 

This utility is most useful on systems with very small disks 

OPTIONS 

-d D ecompress the given executables instead of compressing them 

SEE ALSO 

gzip(l), znew(l), zmore(l), zcmp(l), zforce(l) 

CAVEATS 

The compressed executable is a shell script. This may create some security holes In particular, the compressed executable 
relies on the path environment variable to find gzip and some other utilities (tail, chmod, in, sleep). 

BUGS 

gzexe attempts to retain theoriginal file attributes on thecompressed executable but you may have to fixthem manually in 
some cases, using chmod or chom. 

head 

head- 0 utput thefirst part of files 

SYNOPSIS 

head [-c N[bkm]] [-n N] [-qv] [--bytes=N[bkm]] [--lines=N] [--quiet] [--silent] 

[--verbose] [--help] [--version] [file...] 

head [-Nbcklmqv] [file...] 

DESCRIPTION 

This manual page documents the GN U version of head, head prints the first part (10 lines by default) of each given file; it 
reads from standard input if no files are given or when a filename of - is encountered. If more than onefile is given, it prints 
a header consisting of the file's name enclosed in ==> and <== before the output for each file 

OPTIONS 

head accepts two option formats: the new one in which numbers are arguments to the option letters; and the old one in 
which the number precedes any option letters 

-c n, - -bytes n Print first n bytes n is a nonzero integer, optionally followed by one of the following characters to 

specify a different unit, 
b 512-byte blocks, 
k 1-kilobyte blocks, 
m 1-megabyte blocks 
-l, -n n, - -lines n Print first n lines 
-q, - -quiet, - -silent N ever print filename headers 
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-v, - -verbose Always print filename headers. 

- - help Print a usage message and exit with a nonzero status. 

- -version Print version information on standard output, then exit. 

GNU Ted Utilities 

hexdump 

hexdump— ASCII, decimal, hexadecimal, octal dump 

SYNOPSIS 

hexdump [-bcdovx] [-e format_string] [-f format_file] [-n length] [-s skip] [file ...] 

DESCRIPTION 

T he hexdump utility is a filter that displays the specified files, or the standard input, if no files are specified, in a user-specified 
format. 

T he options are as follows: 

0 ne-byte octal display. D isplay the input offset in hexadecimal, followed by sixteen space- 
separated, three-column, zero-filled bytes of input data, in octal, per line 
0 ne-byte character display. D isplay the input offset in hexadecimal, followed by sixteen space 
separated, three-column, spacefilled, characters of input data per line. 

Two-byte decimal display. Display the input offset in hexadecimal, followed by eight space 
separated, fivecolumn, zero-filled, two-byte units of input data, in unsigned decimal, per line 
Specify a format string to be used for displaying data. 

Specify a file that containsoneor more newline separated format strings Empty lines and lines 
whose first nonblank character is a hash mark (#) are ignored. 

Interpret only length bytes of input. 

T wo-byte octal display. D isplay the input offset in hexadecimal, followed by eight space-separated, 
six-column, zero-filled, two-byte quantities of input data, in octal, per line 
Skipoffset bytes from the beginning of the input. By default, offset isinterpreted asadecimal 
number. W ith a leading ox or ox, offset isinterpreted asa hexadecimal number; otherwise, with a 
leading o, offset isinterpreted as an octal number. Appending the character b, k, or m to offset 
causes it to be interpreted asamultipleof 512,1024, or 1048576, respectively. 

The -v option causes hexdump to display all input data. W ithout the -v option, any number of 
groups of output lines, which would be identical to the immediately preceding group of output 
lines (except for the input offsets), are replaced with a linecomprised of a single asterisk. 

Two-byte hexadecimal display. D isplay the input offset in hexadecimal, followed by eight, space- 
separated, four-column, zero-filled, two-byte quantities of input data, in hexadecimal, per line 

For each input file hexdump sequentially copies the input to standard output, transforming the data according to theformat 
strings specified by the -e and -f options, in the order that they were specified. 

FORMATS 

A format string containsany number of format units, separated by whitespace A format unit contains up to three items: an 
iteration count, a byte count, and a format. 

The iteration count isan optional positive integer, which defaults to one Each format isapplied iteration counttimes 
The byte count is an optional positive integer. If specified, it defines the number of bytes to be interpreted by each iteration 
of the format. 





hexdump 


If an iteration count and/or a byte count is specified, a single slash must be placed after the iteration count and/or before the 
byte count to disambiguate them. Any whitespace beforeor after the slash isignored. 

Theformat is required and must be surrounded by double quote ("") marks. It is interpreted as an tprintf-style format 
string (see tprintf(3)) with thefollowing exceptions: 

■ An asterisk!*) may not be used as a field width or precision. 

■ A byte count or field precision is required for each s conversion character (unlike the tprintf (3) default, which prints 
the entire string if the precision is unspecified). 

■ The conversion characters h, 1, n, p, and q are not supported. 

■ Thesingle-characterescapesequencesdescribed intheC standard are supported: 

NUL \0 

Alert character \a 

Backspace \b 

Form-feed \t 

Newline \n 

Carriage return \r 

Tab \t 

Vertical tab \v 

hexdump also supports the following additional conversion strings 

a[dox] D isplay the input offset, cumulative across input files of the next byte to be displayed. The appended characters 
d, o, and x specify the display base asdecimal, octal, or hexadecimal respectively. 

A[doxj Identical to the a conversion string except that it isonly performed once, when all of the input data has been 
processed. 

c Output characters in the default character set. Nonprinting characters are displayed in three-character, zero- 

padded octal, except for those representable by standard escape notation (see preceding list), which are displayed 
as two-character strings 

p 0 utput characters in the default character set. N onprinting characters are displayed as a single period, 

u 0 utput U .S. ASC11 characters, with the exception that control characters are displayed using the lowercase names 

in thefollowing mini-table. C haracters greater than oxtt, hexadecimal, are displayed as hexadecimal strings. 


000 nul 

001 soh 

002 StX 

003 etx 

004 eot 

005 enq 

006 ack 

007 bel 

008 bs 

009 ht 

00A If 

00B vt 

00C ff 

00D cr 

00E SO 

00F si 

010 die 

011 del 

012 dc2 

013 dc3 

014 dc4 

015 nak 

016 syn 

017 etb 

018 can 

019 em 

01A SUb 

01B esc 

01C fs 

01D gs 

01E rs 

01F US 

OFF del 




The default and supported byte counts for the conversion characters are as follows: 




%_c, %_p, %_u, %c 0 ne-byte counts only. 

%d, %i, %o, %u, %x, %x Four-byte default; one-, two-, and four-byte counts supported. 

%e, %e, %t, %g, %g Eight-byte default, four-byte counts supported. 

The amount of data interpreted by each format string is the sum of the data required by each format unit, which is the 
iteration count times the byte count, or the iteration count times the number of bytes required by theformat if the byte 
count is not specified. 

The input is manipulated in blocks, a block is defined as the largest amount of data specified by any format string. Format 
strings interpreting less than an input block's worth of data, whose last format unit both interprets some number of bytes 
and does not have a specified iteration count, have the iteration count incremented until the entire input block has been 
processed or there is not enough data remaining in the block to satisfy theformat string. 
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If, either as a result of user specification or hexdump modifying the iteration count as described, an iteration count is greater 
than one, no trailing whitespace characters are output during the last iteration. 

It isan error to specify a byte count as well as multiple conversion characters or strings unless all but one of the conversion 
characters or strings is a or a. If, asa result of the specification of the -n option or end-of-file being reached, input data only 
partially satisfies a format string, the input block is zero-padded sufficiently to display all available data (that is, any format 
unitsoverlappingtheend of data will display some number of the zero bytes). 

F urther output by such format strings is replaced by an equivalent number of spaces. An equivalent number of spaces is 
defined as the number of spaces output by an s conversion character with the same field width and precision as the original 
conversion character or conversion string but with any +,"", # conversion flag characters removed, and referencing a null 
string. 

If no format strings are specified, the default display isequi valent to specifying the -x option, 
hexdump exits 0 on success and >0 if an error occurred. 

EXAMPLES 

D isplay the input in perusal format: 

"%06.6_ao " 12/1 "%3_u " 



Implement the-x option: 

"%07.7_Ax\n" 

"%07.7_ax "8/2 "%04x 11 "\n" 

SEE ALSO 

adb(l) 


18 April 1994 


hipstopgm 

hipstopgm— Convert a HI PS file into a portable graymap 

SYNOPSIS 

hipstopgm [hipsfile] 

DESCRIPTION 

Hipstopgm reads a HI PS file as input and produces a portable graymap asoutput. 

If the H IPSfilecontainsmorethan oneframein sequence hipstopgm will con eaten ate all the frames vertically. 
HIPS is a format developed at the Human Information Processing Laboratory, NYU. 

SEE ALSO 

pgm(5) 

AUTHOR 

Copyright © 1989 byjef Poskanzer 


24 August 1989 
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host 

host— Look up hostnames using domain server 

SYNOPSIS 

host [-1] [-V] [-w] |-r; [-d] [-t querytype] [-a] host [ server ] 

DESCRIPTION 

host looks for information about Internet hosts It gets this information from a set of interconnected servers that are spread 
across the country. By default, it simply converts between hostnamesand Internet addresses. H owever with the -t or -a 
options it can be used to find all of the information about this host that is maintained by the domain server. 

The arguments can be either hostnames or host numbers. The program first attempts to interpret them as host numbers. If 
thisfails, it will treat them as hostnames A host number consists of first decimal numbers separated by dots for example 
128.6.4.194. A hostname consists of names separated by dots, for example, topaz.rutgers.edu. Unless the name ends in a 
dot, the local domain ^automatically tacked on the end. Thus, a Rutgers user can say "host topaz", and it will actually look 
up topaz.rutgers.edu. If thisfails the name is tried unchanged (in thiscase, topaz). This same convention is used for mail 
and other network utilities. The actual suffix to tack on the end is obtained by looking at the results of a hostname call, and 
using everything starting at thefirst dot. (Following isa description of how to customize the hostname lookup.) 

The first argument is the hostname you want to look up. If this is a number, an inverse query is done; that is, the domain 
system looks in a separate set of databases used to convert numbers to names. 

The second argument isoptional. It allows you to specify a particular server to query. If you don't specify this argument, the 
default server (normally the local machine) isused. 

If a name is specified, you may see output of three different kinds H ere is an example that shows all of them: 

sun4.rutgers.edu is a nickname for ATHOS.RUTGERS.EDU 
ATHOS.RUTGERS.EDU has address 128.6.5.46 
ATHOS.RUTGERS.EDU has address 128.6.4.4 
ATHOS.RUTGERS.EDU mail is handled by ARAMIS.RUTGERS.EDU 

Theuser hastyped the command host sun4.Thefirstlineindicatesthatthenamesun4.rutgers.edu isactually a nickname 
Theofficial hostnameisATHOs.RUTGERs.EDu. The next two lines show the address If a system hasmorethan one network 
interface, there will be a separate address for each. T he last li ne indicates that athos . rutgers . edu does not receive its own 
mail. M ail for it istaken by aramis.rutgers.edu. There may be more than one such line as some systems have more than one 
other system that will handle mail for them. Technically, every system that can receive mail issupposed to have an entry of 
this kind. If the system receives its own mail, there should bean entry the mentions the system itself, for example "XXX mail 
is handled by XXX." However many systems that receive their own mail do not bother to mention that fact. If a system has a 
"mail is handled by" entry, but no address, this indicates that it is not really part of the Internet, but a system that ison the 
network will forward mail to it. Systems on U senet, bitnet, and a number of other networks have entries of this kind. 

T here are a number of optionsthat can be used before the hostname Most of these options are meaningful only to the staff 
who have to maintain the domain database. 

The option -w causes host to wait forever for a response. N ormally it will time out after around a minute. 

The option -v causes printout to be in a verbose format. This istheofficial domain master file format, which is documented 
in the man page for named. Without this option, output still follows this format in general terms, but some attempt is made 
to make it more intelligible to normal users Without -v, a, mx, and cname records are written outashas address, man is 
handled by, and is a nickname for, and TTL and class fields are not shown. 

The option -r causes recursion to be turned off in the request. This means that the name server will return only data it has in 
its own database. It will not ask other servers for more information. 

Theoption -dturnson debugging. Network transactions are shown in detail. 
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The option -t allows you to specify a particular type of information to be looked up. The arguments are defined in the man 
pagefor named. Currently supported types are a, ns, md, mf, cname, soa, mb, mg, mr, null, wks, ptr, hinfo, minfo, mx, uinfo, uid, 
gid, unspec, and the wildcard, which may be written as either any or *. Types must be given in lowercase Note that the 
default isto look first for a, and then mx, except that if the verbose option is turned on, the default isonly a. 

Theoption -a (for "all") is equivalent to -v -t any. 

The option -1 causes a listing of a complete domain. For example 

host -1 rutgers.edu 

will give a listing of all hosts in therutgers.edu domain. The -t option is used to filter what information is presented, as you 
would expect. The default is address information, which also include PTR and NS records The command host: 

-1 -v -t any rutgers.edu 

will give a complete download of the zone data for rutgers.edu, in the official master file format. (However the SOA record 
is listed twice for arcane reasons) 


NOTE 


-l is implemented by doing a complete zone transfer and then filtering out the information you have asked for. This 
command should be used only if it is absolutely necessary. 


CUSTOMIZING HOSTNAME LOOKUP 

In general, if the name supplied by the user does not have any dots in it, a default domain is appended to the end. This 
domain can be defined in /etc/resoiv.conf, but is normally derived by taking the local hostname after its first dot. The user 
can override this and specify a different default domain, using the environment variable localdomain. In addition, the user 
can supply his own abbreviations for hostnames They should be in afile consisting of one line per abbreviation. Each line 
contains an abbreviation, a space and then the full hostname. This file must be pointed to by an environment variable 
hostaliases, which is the name of the file. 

SEE ALSO 

named(8) 

BUGS 

Unexpected effects can happen when you type a name that is not part of the local domain. Please always keep in mind that 
the local domain nameistacked onto the end of every name unless it ends in a dot. Only if thisfailsisthe name used 
unchanged. 

The -i option only tries thefirst name server listed for the domain that you have requested. If this server is dead, you may 
need to specify a server manually. For example, to get a listing of foo.edu, you could try host -t ns foo.edu to get a list of all 
thenameserversforfoo.edu, and then try host -l foo.edu xxxfor all xxx on the list of name servers, until you find one that 
works 

hostid 

hosttd- Set or print system's host ID. 

SYNTAX 


hostid [-v] [ deci mal - i d ] 




hostname 


DESCRIPTION 

The hostid command prints the current host ID number in hexadecimal and both decimal and hexadecimal in parenthesis if 
the-v option isgiven. This numeric value isexpected to be unique across all hosts and isnormallysetto resemble the host's 
Internet address. 

Only the superuser can set the hostid by giving an argument. This value is stored in thefile/etc/hostid and need only be 
performed once. 

AUTHOR 

hostid iswritten by M itch D'SoUZa (m.dsouza@mrc-apu.cam.ac.uk). 

SEE ALSO 

gethostid(2), sethostid(2) 

hostname 

hostname— Show or set the system's hostname 
dnsdomainname--Show the system's domain name 

SYNOPSIS 

hostname [-d][--domain][-Ff i I ename] [ --filef i I ename ] [-f] [--fqdn][-h][--help] 

[--long][-s][ - -short][-v][--version][name] 
dnsdomainname 


DESCRIPTION 

hostname is the program that is used to either set the hostname or display the current host or domain name of the system. 
This name is used by many of the networking programsto identify the machine 

When called without any arguments, the program displays the current name asset by the hostname command. You can 
change the output format to display always the short or the long hostname (FQ D N). When called with arguments, the 
program will set the value of the hostname to the value specified. This usually is done only once at system startup time by 
the /etc/rc.d/rc.ineti configuration script. 

N otethat only the superuser can change the hostname. 

If the program was called as dnsdomainname, it will show the domain name server (D N S) domain name You can’t change the 
DNSdomain name with dnsdomainname. (Seethefollowing subsection.) 


OPTIONS 

-F, - -file filename 
-f, --fqdn, --long 




D isplay the name of the D N S domain. D on’t use the com-mand domainname to get the D N S 
domain name because it will show the N IS domain name and not the DN S domain name 
Read the hostname from the specified file Comments (lines starting with a#) areignored. 
Display the FQD N (fully-qualified domain name). An FQDN consists of a short hostname and 
theD NS domain name Unless you are using bind or NIS for host lookups, you can change the 
FQDN and the DNS domain name (which is part of the FQDN) in the/etc/hosts file. 

Print a usage message on standard output and exit successfully. 

D isplay the short hostname 

Print verson information on standard output and exit successfully. 


FILES 


/etc/hosts 
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AUTHOR 

PfiterTobias, (tobias@server.et-inf.fho-emden.de) 


Linux, 28July 1994 


hpcdtoppm v0.3 

hpcdtoppm vO.3— Convert a Photo-C D file into a portable pixmap 

SYNOPSIS 

hpcdtoppm [options] pcd-file [ppm-file] 


DESCRIPTION 

hpcdtoppm reads a Photo-CD image file or overview file and outputs a portable pixmap. Image files you can find on the 
Photo-CD in photo_cd/images are named asimgnnnn .pcd, where nnnn is a 4-digit-number. The Overview file is at photo_cd/ 
overview.pcd. If there isno ppm-file given, output will be printed to stdout. hpcdtoppm stands for "Hadmut'spcdtoppm"to 
make it distinguishable in case someone else is building the same thing and calling it pcdtoppm. 


OPTIONS 


-1 | -Base/16 | -128x192 

-2 | -Base/4 | -256x384 
-3 | -Base | -512x768 
-4 | -4Base | -1024x1536 
-5 | -16Base ] -2048x3072 
-0 | -Overview ] -0 




Give some information fromthefileheaderto stderr. It works only forimage files (Itisnot 
working correctly, just printing some strings.) 

Apply simple sharpness-operator on the luma channel. 

D o not show the complete i mage, but only the decompressed difference It works only on 
the4Base and the 16Base resolution. It does not have any deeper sense but it was simple to 
implement and it shows what causes different sizes of image files 
Rotate the picture clockwise for portraits. 

Rotate the picture counter-clockwise for portraits 

Try to find out the image orientation. Thisdoesn't work for overview files yet. It is very 
experimental and depends on one byte. Please tell me if it doesn't work. 

Overskip mode. Workson Bas^l6, Bas^4, Base and 4Base. In Photo-CD images the 
luma channel isstored in full resolution, the two chroma channels are stored in half 
resolution only and have to be interpolated. In the Overskip mode, the chroma channelsof 
the next higher resolution are taken instead of interpolating. To see the difference generate 
one ppm with and one ppm without thisflag. Usepnmarith to generate the difference image of 
these two images Call ppmhist forthisdifferenceorshow it with xv (push theH istEq 
button in the color editor). 

Extract the Base/16 size picture (size 128x192 pixels). N otethat you can only giveonesize 
option. 

Extract the Base/4 size picture. 

Extract the Base size picture. 

Extract the 4Base size picture. 

Extract the 16Basesize picture. 

Extract all pictures from an Overview file. A ppm filename must be given. If the given name 
isfoo, thefiles are named toonnnn, wherennnn is a 4-digit number. They are stored in 
Bas^l6 format, so they are extracted in thisformat. 

Suppress the ycc to rgb conversion. This is experimental only. You can use this and apply 
ppmtorgb3 on thefile Then you will get three pgm files one luma and two chroma files 
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BUGS 

I still don't have enough information about the Photo-CD to take care of all data structures The information I haveisquite 
vague and this program was developed by staring at the hexdumps and using the famous trial-and-error-method.:-) If 
anything doesn't work, please send me a report and perhaps you could try to find out why it doesn't work. 

SEE ALSO 

ppm(5), ppmquant(l), ppmtopgm(l), ppmhist(l), pnmarith(l), ppmtorgb3(l), xv(l) 

AUTHOR 

Copyright© 1992 by H admut Danisch (danisch@ira.uka.de). Permission to use and distribute thissoftware and its 
documentation for noncommercial use and without fee is hereby granted, provided that the preceding copyright notice 
appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. 

This software may not be sold in anyway. Thissoftware is not public domain. 

28 N ovember 1992 


httpd 

httpd- Apache H ypertext Transfer Protocol server 

SYNOPSIS 

httpd [ -vX? ][-d server root ][-f config ] 


DESCRIPTION 

httpd istheApacheH ypertext Transfer Protocol (HTTP) server process. The server may be invoked by the Internet daemon 
inetd(lM) each time a connection to the HTTP service is made, or alternatively it may run as a daemon. 


OPTIONS 


Set the initial value for the Server-Root variable to server-root. Thiscan be overridden by theserverRoot 
command in the configuration file The default is/usr/iocai/etc/httpd. 

Execute the commands in the file conf i g on startup. If conf i g does not begin with a/, then it is taken to 
be a path relative to theserverRoot. The default is conf /httpd. conf. 

Run in single-process mode, for internal debugging purposesonly; the daemon does not detach from the 
terminal or fork any children. Donot use thismode to provide ordinary Web service. 

Print the version of httpd, and then exit. 

Print a list of the httpd options, and then exit. 


FILES 

/usr/local/etc/httpd/conf/httpd.conf 
/usr/local/etc/httpd/conf/srm.conf 
/usr/local/etc/httpd/conf/access.conf 
/usr/local/etc/httpd/conf/mime.types 
/usr/local/etc/httpd/logs/error_log 
/usr/local/etc/httpd/logs/access_log 
/usr/local/etc/httpd/logs/httpd.pld 

SEE ALSO 

inetd(lm) 

Documentation for the Apache HTTP server is available from http://www.apache.org. 


October 1995 
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icontopbm 

icontopbm—Convert a Sun icon into a portable bitmap 

SYNOPSIS 

icontopbm [iconfile] 

DESCRIPTION 

icontopbm readsaSun icon asinputand produces a portable bitmap as output. 

SEE ALSO 

pbmtoicon(l), pbm(5) 

AUTHOR 

Copyright© 1988 byjef Poskanzer 

31 August 1988 


ident 

ident— Identify RCS keyword strings in files 

SYNOPSIS 

ident [ -q ][-V ] [fiI e ... ] 

DESCRIPTION 

ident searchesfor all instancesof the pattern $ keyword ; text $ in the named files or, if no files are named, the standard 
input. 

These patterns are normally inserted automatically by the RCS command co(l), but can also beinserted manually.The 
option -q suppresses the warning given if there are no patterns in a file The option -v prints ident's version number, 
ident workson text files as well asobject files and dumps For example iftheC program in t.c contains 
#include <stdio.h> 
static char const rcsid[] = 

"$Id: f.c,v 5.4 1993/11/09 17:40 eggert Exp $"; 
int main)) { return printf("%s\n", rcsid) — EOF; } 

and f.c is compiled intot.o, then the command 


will output 

$Id: f.c,v 5.4 1993/11/09 17:40 eggert Exp $ 

$Id: f.c,v 5.4 1993/11/09 17:40 eggert Exp $ 

If aC program defines a string like the rcsid but does not use it, imt(l) may complain, and someC compilers will optimize 
away the string. The most reliable solution isto have the program use the rcsid string, as shown in the example 
ident finds all instances of the $ keyword : text $ pattern, even if keyword isnot actually an RCS-supported keyword. This 
gives you information about nonstandard keywords like $xconsortium$. 
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KEYWORDS 

H ere isthe list of keywords currently maintained by co(l). All times are given in Coordinated U niversal TimefUTC, 
sometimes called GMT by default), but if the files were checked out with co's-zzone option, times are given with a numeric 
timezoneindication appended. 

$Author$ Thelogin nameof the user who checked in the revision. 

$Date$ Thedateand timetherevision waschecked in. 

$Header$ A standard header containing thefull pathname of the RCS file the revision number, thedateand time, 

the author, the state and the locker (if locked). 

$id$ Same as$Header$, except that the RC S filename is without a path. 

$Locker$ The login nameof the user who locked the revision (empty if not locked). 

$Log$ The log message supplied during checkin. For ident’s purposes, this is equivalent to $RCSfiie$. 

$Name$ The symbolic name used to check out the revision, if any. 

$RCSfiie$ T he name of the RC S file without a path. 

$Revision$ Therevision number assigned to therevision. 

$source$ Thefull pathname of the RC S file. 

$state$ The state assigned to therevision with the-s option of rcs(l) or ci(l). 

co( 1) represents the following characters in keyword values by escape sequences to keep keyword strings well formed. 

Character Es^pe Sequence 

Tab \t 

Newline \n 

Space \040 

$ \044 

\ w 

IDENTIFICATION 

Author: Walter F.Tichy 

M anual Page Re/ision: 5.4; Release date September 11,1993. 

Copyright© 1982,1988,1989 Walter F. Tichy. Copyright© 1990,1992,1993 Paul Eggert. 

SEE ALSO 

ci( 1), co(l), rcs(l), rcsdiff(l), rcsintro(l), rcsmerge(l), rlog(l), rcsfile(5) 

Walter F. Tichy, RCS-A System for Version Control, Software-Practice & Experience 15,7 (July 1985), 637-654. 

GNU, 9 November 1993 


ilbmtoppm 

ilbmtoppm— Convert an ILBM file into a portable pixmap 

SYNOPSIS 

ilbmtoppm [-verbose][-ignore<chunkID>] [-isham]-isehb][-adjustcolors][ILBMfile] 

DESCRIPTION 

ilbmtoppm reads an IFF I LBM file as input and produces a portable pixmap as output. Supported I LBM types are N ormal 
ILBMs with 1-16 planes. 
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Amiga Extra H alfbrite (EH B) 

Amiga HAM with 3-16 planes 
24-bit 

M ultiplatte (normal or H AM) pictures 
Colormap (bmhd and cmap chunk only, nPianes = 0) 

Unofficial direct color; 1-16 planes for each color component. 

Chunks used; bmhd, cmap, camg (only HAM and EH B flagsused), pchg, body unofficial dcol chunk to 

identify direct color ILBM 

C hunks ignored; grab, dest, sprt, crng, ccrt, clut, dppv, drng, epsf 

Other chunks (ignored but 

displayed in verbose mode): name, auth, (d), anno, dpi 

Unknown chunks are skipped. 


OPTIONS 

-verbose 

-ignore <chunkID> 


-adjustcolors 


Give some information about thelLBM file. 

Skip a chunk. <chunkiD> isthe 4-letter iff chunk identifier of the chunk to be skipped. 

T reat theinput file as a ham or Extra H alfbrite picture, even if these flags or not set in the camg 
chunk (or if there is no camg chunk). 

If all colors in the cmap have a value of less then 16, iibmtoppm assumes a 4-bit colormap and gives a 
warning. W ith this option, the colormap is scaled to 8 bits 


BUGS 

ThemultipalettePCHG BigLineChanges and H uffman decompression code are untested. 

REFERENCES 

Amiga ROM Kernel ReferenceM an ual-Devices (3rd Ed.). Addison Wesley, ISBN 0-201-56775-X. 

SEE ALSO 

ppm(5), ppmtoilbm(l) 

AUTHORS 

Copyright© 1989 byjef Poskanzer. 

M odified October 1993 by Ingo W ilken (lngo.Wilken@informatik.uni-oldenburg.de) 

4 October 1993 


imake 

imake— C preprocessor interface to the make utility 

SYNOPSIS 

imake [ -Ddef i ne ] [-Id i r ] [-Ttempl ate ] [ -f f i I e n a me ][-C f i I ename ] [-s f i I ename ] 
l-e ][-v ] 

DESCRIPTION 

imake isused to generate Makefiles from a template a set of cpp macro functions, and a per-directory input file called an 
imakefiie. This allows machine dependencies (such ascompiler options, alternate command names, and special make rules) to 
be kept separate from the descri ptions of the various items to be bui It. 



imake 


OPTIONS 

Thefollowing command-line options maybe passed to imake: 

-Ddef i ne Thisoption is passed directly to cpp. It istypically used to set directory-specific variables. For example, the 

X W indow System uses this flag to set topdir to the name of the directory containing the top of the core 
distribution and curdir to the name of the current directory, relative to the top. 

-idi rectory Thisoption is passed directly to cpp. It istypically used to indicate the directory in which theimake 
template and configuration files may befound. 

-Ttempi ate Thisoption specifies the name of the master template file (which is usually located in the directory 
specified with -i) used by cpp. T he default is imake. tmpi. 

-f f i i ename Thisoption specifies the name of the per-directory input file. The default is imakefiie. 

-c f i i e n a me Thisoption specifies the name of the .c file that is constructed in thecurrent directory. The default is 

Imakefile.c. 

-s f i i ename Thisoption specifies the name of the make description file to be generated but make should not be invoked. 

If the filename is a hyphen (-), the output is written to stdout. The default is to generate, but not execute, 
a Makefile. 

-e Thisoption indicates the imake should execute the generated Makefile. The default is to leave this to the 

user. 

-v Thisoption indicates that imake should print the cpp command line that it is using to generate the 


imake invokes cpp with any -i or -d flags passed on the command line and passes the name of a file containing the following 
three lines: 


where imake. tmpi and imakefiie may be overridden by the-T and -f command options, respectively. 

The imake_template typically reads in a file containing machine-dependent parameters (specified as cpp symbols), a site- 
specific parameters file, a file defining variables, a file containing cpp macro functions for generating make rules, and finally 
the imakefiie (specified by include_imakefile) in thecurrent directory. The imakefiie uses the macro functionsto indicate 
what targets should be built; imake takes care of generating the appropriate rules 

imake configuration files contain two types of variables imake variables and make variables. Theimake variables are interpreted 
by cpp when imake is run. By convention they are mixed case. The make variables are written into the Makefile for later 
interpretation by make. By convention make variables are uppercase 

The rules file (usually named imake. rules in the configuration directory) containsa variety of cpp macro functions that are 
configured according to thecurrent platform, imake replaces any occurrences of the string @@ with a newline to allow macros 
that generate more than onelineof make rules. For example, when called with program_target(foo, fooi.o foo2.o),the 
macro: 

#define program_target(program, objlist) @@\ 

program: objlist 

$(CC) -0 $@ objlist $(LDFLAGS) 

will expand to 

$(CC) -0 $@ fooi.o f002 .0 $(LDFLAGS) 

imake also replaces any occurrences of the word xcomm with the character # to permit placing comments in the Makefile 
without causing invalid directive errorsfrom the preprocessor. 
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Some complex imake macros require generated make variables local to each invocation of the macro, often because their value 
depends on parameters passed to the macro. Such variables can be created by using an imake variable of the form xvARdefn, 
where n is a single digit. A unique make variable will be substituted. Later occurrences of the variable xvARusen will be replaced 
by the variable created by the corresponding xvARdefn. 

0 n systems whose cpp reduces multiple tabs and spaces to a single space, imake attempts to put back any necessary tabs (make 
is very picky about the difference between tabs and spaces). For this reason, colons (:) in command lines must be preceded 
by a backslash (\). 

USE WITH THE X WINDOW SYSTEM 

TheX Window System uses imake extensively, for both full builds within the source tree and external software. As men¬ 
tioned earlier, two special variables, topdir andcuRDiR, aresdtto make referencing files using relative pathnames easier. For 
example, thefollowing command is generated automatically to build theMakefiie in the directory iib/x/ (relative to the top 
of the sources): 

% /config/imake -I/config \ 

-DTOPDIR=.-DCURDIR=./lib/X 

When building X programs outside the source tree, a special symbol useinstaiied isdefined and topdir and cuRDiRare 
omitted. If the configuration fileshavebeen properly installed, the script xmkmt(l) may be used. 

INPUT FILES 

FI ere is a summary of the files read by imake as used by X. The indentation shows which files include which other files 

Imake.tmpl generic variables 

site.def site-specific, BeforeVendorCF defined 

.cf machine-specific 

Lib.rules shared library rules 

site.def site-specific, AfterVendorCF defined 

Imake.rules rules 

Project.tmpl X-specific variables 

Lib.tmpl shared library variables 

Imakefile 

Library.tmpl library rules 
Server.tmpl server rules 
Threads.tmpl multi-threaded rules 

Note that site.def is included twice, once before the *.cf file and once after. Although most site customizations should be 
specified after the *.cf file some, such as the choice of compiler, need to be specified before, because other variable settings 
may depend on them. 

Thefirst time site.def isincluded, the vari able BeforeVendorCF isdefined, and the second time, the variable AfterVendorCF is 
defined. All code in site.def should beinsidea#ifdef for one of these symbols. 

FILES 

imakefile. c T emporary input file for cpp 
/tmp/imf .xxxxxx Temporary Makefile for -s 

/tmp/iif .xxxxxx Temporary imakefile if specified imakefile uses # comments 
/lib/cpp D efault C preprocessor 

SEE ALSO 

make(l), xmkmf(l) 

S. I. Feldman, M ake- A Program for M aintainingComputer Programs 




/news 

ENVIRONMENT VARIABLES 

Thefollowing environment variables may beset; however, their use is not recommended as they introduce dependencies that 
are not readily apparent when imake is run. 

imakeinclude If defined, thisshould beavalid include argument for the C preprocessor. Example 
-I/usr/include/local 

Actually, any valid cpp argument will work here. 
imakecpp If defined, thisshould beavalid path to a preprocessor program. Example 

/usr/local/cpp 

By default, imake will use /nb/cpp. 

imakemake If defined, thisshould beavalid path to a make program, such as 
/usr/local/make 

By default, imake will use whatever make program isfound using execvp(3). This variable is only used if the 
-e option isspecified. 

AUTHORS 

Todd Brunhoff, Tektronix and M IT Project Athena 
Jim Fulton, M IT X Consortium 

X Version 11 Release 6 

imgtoppm 

imgtoppm— Convert an img-whatnot file into a portable pixmap 

SYNOPSIS 

imgtoppm [imgfile] 

DESCRIPTION 

imgtoppm reads an img-whatnot file as input and produces a portable pixmap as output. The img-whatnot toolkit is available for 
FTP on venera.isi.edu, along with numerous images in thisformat. 

SEE ALSO 

ppm(5) 

AUTHOR 

Based on a simple conversion program posted to comp.graphics by Ed Falk. 

Copyright© 1989 byjef Poskanzer. 

5 September 1989 



inews 

inews— Send a U senet article to the local news server for distribution 


SYNOPSIS 



Parti: User Commands 


DESCRIPTION 

mews reads a Usenet news article (perhaps with headers) from the named file or standard input if no file isgiven. It adds 
some headers and performs some consistency checks If the article does not medt these checks (for example too much 
quoting of old articles or posting to nonexistent newsgroups), then the article is rqected. If it passes thechecks, inews sends 
the article to the local news server as specified in theinn.conf(5) file for distribution. 

In the standard mode of operation, the input consists of the article headers, a blank line, and the message body. For com¬ 
patibility with older software, the -h flag must be used. If there are no headers in the message then thisflag may be omitted. 
Several headers may be specified on the command line shown in the synopsis above as header flags Each of these flags takes 
a single parameter; if the value is more than one word (for example almost all Subject lines) then quotes must be used to 
prevent the shell from splitting it into multiple words. The options and their equivalent headers, are as follows: 
a Approved 

c Control 

d Distribution 

e Expires 

f From 

w Followup-To 

n N ewsgroups 

r Reply-To 

t Subject 

F References 

o Organization 

x Path prefix 

The Path header is built according to the following rules If the-x flag is used, then its value will be the start of the header. 
Any other host will see the site in the header, and therefore not offer the article to that site If thepathhost configuration 
parameter is specified in the inn. conf(5) file then it will be added to the Path. Otherwise, if the server configuration 
parameter is specified, then thefull domain name of the local host will be added to the Path. The Path will always end 

The default 0 rganization header will be provided if none is present in the article or if the-o flag is not used. T o prevent 
adding the default, use the-o flag. 

As a debugging aide if the -d flag is used, the consistency checks will be performed, and the article will be sent to the 
standard output, rather then sent to the server. 

For compatibility with C News, inews accepts, but ignores, the -a, -v,and -w flags. TheC News-Nflagistreated as the -d flag. 
If a file named .signature exists in the user's home directory, inews will try to append it to the end of the article If the file 
cannot be read, or if it is too long (for example, more than four lines or one standard I/O buffer), or if some other problem 
occurs, then the article will not be posted. To suppress this action, use the-s flag. 

If the -r flag isused then inews will rqect any attempts to post control messages. 

If an unapproved posting ismadeto amoderated newsgroup, inews will try to mail the article to the moderator for posting. 
It uses the moderators(5) file to determine the mailing address If no address is found, it will usetheinn.conf file to 
determine a "last-chance" host to try. 

If the N N TP server needs to authenticate the client, inews will usetheNNTPsendpass-word(3) routine to authenticate itself. In 
order to do this, the program will need read access to the passwd.nntp(5) file. This is typically done by having thefile group- 
readable and making inews run setgid to that group. 

mews exits with a zero status if the article was successfully posted or mailed, or with a nonzero status if the article could not 
be delivered. 




info 

Since inews will spool its input if the server is unavailable, it is usually necessary to run rnews(l) with the -u flag on a regular 
basis, usually out of cron(8). 

HISTORY 

Written by Rich $alz(rsaiz@uunet.uu.net)for/nterNetNews 

SEE ALSO 

moderators(5), inn.conf(5). rnews(l) 



info 

info- G N U's hypertext system 

SYNOPSIS 

info [ --option-name option-value ] enu-item... 

DESCRIPTION 

TheGNU project has a hypertext system called info that allows the same source file to be either printed as a paper manual, 
or viewed using info. It is possible to use the info program from inside E macs, or to use the standalone version described 
here This manual page gives a brief summary of its capabilities. 


OPTIONS 

--directory directory-path Add di r ect ory-pat h to the list of directory paths searched when info needs to find a file. 

You may issue --directory multiple times Alternatively, you may specify a value for the 
environment variable infopath; if - -directory is not given, the value of infopath is used. 
The value of infopath is a colon-separated list of directory names. If you do not supply 
either infopath or - di rectory-path, info uses a default path. 

-f filename Specify a particular info fileto visit. By default, info visitsthe file dir; if you usethis 

option, info will start with (filenamejtop asthefirst file and node 
-n no den a me Specify a particular node to visit in the initial file that info loads This is especially useful in 

conjunction with - -file. You may specify - -node multiple times 
-o file Direct output to file instead of starting an interactive info session. 

-h Produce a relatively brief description of the available info options. 

--version Print the version information of info and exit. 

menu-item info treats its remaining arguments asthe names of menu items. The first argument isa 

menu item in theinitial node visited, while the second argument isa menu item in the first 
argument's node You can easily move to the node of your choice by specifying the menu 
names that describe the path to that node For example, info emacs buffers first selects the 
menu item emacs in the node (dir)Top, and then selects the menu item buffers in the node 


COMMANDS 

In info, the following commands are available: 
h Invokethe info tutorial. 

? Get a short summary of info commands 

h Select the info node from the main directory; this is much more complete than just using?, 

ctn-g Abort whatever you are doing, 

ctn-i Redraw thescreen. 
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Selecting other nodes: 

n Move to the next node of this node, 

p M oveto the previous node of this node, 

u M oveto this node's up node. 

m Pick a menu item specified by name Picking a menu item causes another node to be selected. You do not need to 

type a complete nodename; if you type a few letters and then a space or tab, info will try to fill in the rest of the 
nodename. If you ask for further completion without typing any more characters, you'll be given a list of 
possibilities; you can also get the list with ?. If you typeafew characters and then hit Enter, info will try to do a 
completion, and if it isambiguous, usethefirst possibility. 

f Follow a cross reference You are asked for the name of the reference using command completion asfor m. 

1 Move to the last node you were at. 

Moving within a node 
space Scroll forward a page. 

del Scroll backward a page, 

b Go to the beginning of this node 

Advanced commands: 
q Quit info. 

i Pick first item in node's menu. 

2-5 Pick second to fifth item in node's menu. 

g M oveto node specified by name You may include a filename as well, as (filename)nodename. 

s Search through this info filefor a specified string, and select the node in which the next occurrence is 

found. 

m-x print-node Pipe the contents of the current node through the command in the environment variable 
info_print_command. If the variable does not exist, the node is simply piped to ipr. 

ENVIRONMENT 

infopath A colon-separated list of directoriesto search for info files. Used if --directory is not given. 

info_print_command Thecommand used for printing. 

SEE ALSO 

emacs(l) 

AUTHOR 

Brian Fox, Free Software Foundation (bfox@ai.mit.edu) 

MANUALAUTHOR 

Robert Lupton (rhl@astro.princeton.edU); Updated by RobertJ. Chassell (bob@gnu.ai.mit.edu). 

7 D ecember 1990 

innconfval 

innconfvai—Get an /nterN etN ews configuration parameter 

SYNOPSIS 



insmod 
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DESCRIPTION 

innconfvai prints the values of the parameters specified on thecommand line. Values are retrieved from theinn.conf( 5 ) file 
and are described there 

Values are retrieved by using theGetconfigvaiue routine, or GetFiieConfigvaiue if the-f flag is used. Both aredescribed in 
libinn(3). 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for I nterN etl\l ews 

SEE ALSO 

libinn(3), inn.conf(5) 

insmod 

insmod— Install loadable modules (aout and elf format) 

SYNOPSIS 

insmod [ -fkmsxv ] [ -o internal_name ] object_file [ symbol=value ... ] 

DESCRIPTION 

insmod installs a loadable module in the kernel. 

insmod tries to load a module into the kernel, and resolves all symbolsfrom theexported kernel symbols, with version 
information, if available The module will get its name by removing the .0 extension from the basename of the object file. If 
the .0 extension isomitted, insmod will attempt to locate the module in some common default directories If the environ¬ 
ment contains the variable modpath, where all directories are separated with :, insmod will look in these directories for the 
module in the specified order. 

It is possible to load unversioned modules in a versioned kernel, and all combinations of these 
It is also possible to load ELF modulesinto an a.out kernel, and all combi nations of these 

It is possible to stack modules, that is, Idt one module use a previously loaded module. All modules that are referenced are 
updated with this reference This ensures that a module can't be unloaded if there is another module that refers to it. 

It is possible to change integer values in the module when loading it. This makes it possible to tune the module. 

T he options are as follows: 

-t T he -f option tries to load the module even if the kernel or symbol versions differs from the 

version expected by the module. A warning will be issued if the module is locked to a 
specific kernel version that differs from the current version. 

-k This option should really only be used by modprobe.to indicate that the module insertion 

was requested by kerneid. All modules inserted using this option will be subject to 
autoremoval by the kerneid utility if they have been unused for more that a minute. (The 
usage count is zero and no modules depend on this module.) If the kernel is not kerneid- 
aware the module will berqected by the kernel. Just load it without the -k option, and all 
should be well. 

-m The -m option will make insmod output a load map, that will make it easier to debug your 

modules after a kernel panic, thanksto Derek Atkins(wariord@MiT.EDu). 

-0 The-o option allows the module to be named to an explicit name instead of having a name 

derived from the name of the object file. N ote that this option can also be placed after the 
module name, so that the syntax of insmod looks more similar to id. 
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symboi=vaiue[ .value] ... The values of all integer or character pointer symbols in the module can be changed at load¬ 
time by naming a symbol and giving the new value(s). If the symbol is defined as an array of 
integers or character pointers, the elements in the array can be initialized by giving the 
values separated by commas. Specific array entries can be skipped by omitting the value, as 
in symboi=vai uei , ,vai ue2 . Each integer value can be given as a decimal, octal, or hexadeci¬ 
mal value: 17,021, or 0x11. If the first character in the given value is nonnumeric, the value 
is interpreted as a string. The symbol is assumed to be a character pointer, which will be 
initialized to point to the string. Extra space in the module will be allocated for the string 
itself. N ote the syntax: no spaces are allowed around the = or, signs! 

-s W ith this option, insmod will produce debugging information and error messages using the 

sysiog facility. (Also used by kerneid, if you haveinstalled it.) 

-v If you want verbose information from theloading, select thisoption. 

-x The no-export flag, which will inhibit the default insmod behavior-inserting all the 

module's external symbols into the kernel symbol table. N ote that the kernel will still 
update the references that the module makes to previously loaded modules 


SEE ALSO 

rmmod(l), modprobe(l), depmod(l), lsmod(l), ksyms(l), modules( 2 ), genksyms( 8 ) 

HISTORY 

The module support was first conceived by Anonymous (asfar as I know). Linux version by BasLaarhoven (bas@vimec.m). 
0.99.14 version byJonTombs(jon@gtex02. us.es). Extended by Bjorn Ekwall (bj0m@biox.se). ELF help from Eric 
Youngdale (eric@aib.com). 

BUGS 

insmod relies on the "fact" that symbols, for which one wants to change the value, are defined as integers or character 
pointers, and that sizeof(int) == sizeof(char *). 

Linux, 14 May 1995 
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install— Copy files and set their attributes GN U file installer 

SYNOPSIS 

install [options] ]-s] [--strip] source dest 
install [options] ]-s] [--strip] source... directory 
install [options] ]-d,--directory] directory... 

Options: 

]-c] ]-g group] [-m mode] [-0 owner ] [--group=g roup] [--mode=mode] 
[--owner=owner ] [--help] [--version] 


DESCRIPTION 

This manual page documents the G N U version of install, install copies files and sets their permission modes and, if 
possible their owner and group. Used similarly to cp; typically used in Makefiles to copy programs into their destination 
directories. It can also be used to create the destination directories and any leading directories, and to set thefinal directory's 
modes. 11 refuses to copy files onto themselves. 
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OPTIONS 

Ignored; for compatibility with old UNIX versions of install. 

Create each given directory and its leading directories, if they do not already exist. Set the owner, 
group, and mode as given on the command line or to the defaults. Also gives any leading directories 
that are created those attributes This is different from the SunOS 4.x install, which gives 
directories that it creates the default attributes 

set the group ownership of the installed file or directory to the group ID of g r o u p (default is 
process's current group), group may also be a numeric group ID. 

set the permission mode for the installed file or directory to mode, which can be either an octal 
number, or a symbolic mode as in chmod, with 0 as the point of departure. The default mode is 

0755. 

If run as root, sdt the ownership of the installed file to the user ID of owner (default is root), owner 
may also be a numeric user ID. 

Strip the symbol tables from installed programs. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output and exit successfully. 

GNU File Utilities 
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installit— Fil^directory installation tool 

SYNOPSIS 

installit [ -0 owner ][-g group ] [-0 owner ][-G group ][-m mode ][-b backup ] 

[-s j[-t ] source destination 

DESCRIPTION 

installit putsa Copy Of source into the Specified destination. 

If source isa period, then dest i nat i on is taken to be the name of a directory that should be created. Otherwise, source is 
taken to name an existing file and destination may be either a file or directory; it is interpreted according to the same rules 
ascp(l). 

If dest i nat i on names a preexisting file, it will be removed before the copy is done. To make a backup copy, use the-b flag; 
the existing file will be renamed to have the specified extension. If source and dest i nat i on are the same string, or if the two 
files are identical, then no copying isdone and only the -o, -g, -m,and -s flags are processed. I n thiscase, the modification 
ti me on the destination will be updated using touch(l) unless the -n (don't touch) flag is used. 

After thedesti nat i on has been created, it is possible to set the owner, group, and mode that it should have. This is done by 
using the-o, -g, and -m flags, respectively. The -o and -g flags set the owner and group only if installit is being run by root, 
as determined bywhoami(l). To strip(l) an installed executable, use the -s flag. 

N otethat installit uses no special privileges to copy files from one place to another. 

BUG SAND LIMITATIONS 

Flagscannotbecombined. 

Thechom(8) command must exist in either the /etc or /usr/etc directory or the user's path. 

Thewhoami command must exist in the /usr/ucb directory or the user's path. 





Parti: User Commands 


274 


HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for I nterN etl\l ews 

ispell, buildhash, munchlist, findaffix,tryaffix,icombine, 
ijoin 

ispell, buildhash, munchlist, findaffix, tryaffix, icombine, ijoin--I nteractiveSpelling checking 

SYNOPSIS 

ispell [common-f I ags][-M]-N][-Lcontext ] [-V] files 

ispell [common-f I ags ] -1 

ispell [common-f I ags][-f file] [-s]-a| -A 

ispell [-d file][-w chars ] -c 

ispell [-d f i I e] [ -w chars] -e[e] 

ispell [-d file] -D 

ispell -v[v] 

common-flags:[-tll-nj[-b][-x][-B][-C][-P][-m][-S][-d f i I e][-p f i I e][-w chars] 

[-W - ][-T type] 


buildhash [-s] diet-file affix-file hash-file 

buildhash -s count affix-file munchlist [-1 aff-fi I e][-c conv-file] 

[-T suffix] [-s hash-file] [-D][-v][-w chars][f i I es] findaffix [-p|-s][-f] Nfl 
[-m mi n][-M max ] [-e el i m][-t t a be ha r ] [-1 I ow] [f I I es ] 


tryaffix [-p|-s] [-c] expanded-f I I e affix[+addi t i on] 

icombine [-T type][aff-fiIe] 

ijoin [-s]-u] join-options filel file! 

DESCRIPTION 

ispeii isfashioned after the spell program from ITS (called ispell on Twenex systems) The most common usage is ispell 
filename. In thiscase, ispeii will display each word which does not appear in the dictionary at the top of the screen and 
allow you to change it. If there are "near misses" in the dictionary (words that differ by only a single letter, a missing or extra 
letter, a pair of transposed letters or a missing spaceor hyphen), then they are also displayed on following lines. Aswell as 
near misses ispeii may display other guesses at waysto make the word from a known root, with each guess preceded by 
question marks. Finally, the line containing the word and the previous line are printed at the bottom of the screen. If your 
terminal can display in reverse video, the word itself is highlighted. You have the option of replacing the word completely or 
choosing one of the suggested words C ommands are si ngle characters as follows (case is ignored): 
r Replacethemisspelled word completely. 

Space Accept the word thistimeonly. 
a Accept the word for the rest of this ispeii session, 

i Accept the word, capitalized asitisin the file and update private dictionary, 

u Accept the word, and add an uncapitalized (actually, all lowercase) version to the private dictionary. 

0 -n Replacewith one of the suggested words 

l Look up words in system dictionary (controlled by thewoRDS compilation option), 

x W rite the rest of thisfile, ignoring misspellings and start next file. 

q Exit immediately and leave the file unchanged. 

i Shell escape. 






ispell, buildhash, munchlig, findaffix, tryaffix, icombine, ijdn 


0 


■l Redraw screen. 

*z Suspend ispeii. 

? Give help screen. 

If the -m avitch is specified, a one-line mini-menu at the bottom of the screen will summarize these options. Conversely, the 
-n avitch may be used to suppress the mini-menu. (The mini-menu isdisplayed by default if ispeii was compiled with the 
minimenu option, but these two switches will always override the default.) 

If the -l flag isgiven, the specified number is used as the number of lines of context to be shown at the bottom of the screen. 
(T he default is to calculate the amount of context as a certain percentage of the screen size) T he amount of context is subject 
to a system-imposed limit. 

If the-v flag isgiven, characters that are not in the 7-bit AN SI printable character set will always be displayed in thestyle of 
cat -v, even if ispeii thinksthat these characters are legal ISO Latin-1 on your system. Thisis useful when working with 
older terminals Without this avitch, ispeii will display 8-bit characters as is if they have been defined as string characters for 
the chosen file type. 

Besidesthe-i, -a, and -a options N ormal mode acceptsthe following common flagson the command line: 

-t T he input file is in TeX or LaTeX format. 

-n Theinputfileisin nroff/troff format. 

-b Create a backup file by appending .bak to the name of the input file 
-x Don’t create a backup file 

-b Report run-together words with missing blanks as spelling errors 
-c C onsider run-togdther words as legal compounds 
-p D on’t generate extra root/affix combinations. 

-m M ake possible root/affix combinationsthat aren't in the dictionary. 

-s Sort the list of guesses by probable correctness. 

-d file Specify an alternate dictionary file. For example use-d deutsch to choose a German dictionary in a German 
installation. 

-p f i i e Specify an alternate personal dictionary. 

-w chars Specify additional characters that can be part of a word. 

-w n Specify length of wordsthat are always legal. 

-t type Assume a given formatter type for all files 

The-n and -t options select whether ispeii runs in nroff/troff (-n) orTeX/LaTeX (-t) input mode (The default is 
controlled by the deftexflag installation option.) TeX/LaTeX mode is also automatically selected if an input file has the 
extension .tex, unlessoverridden by the-n switch. In TeX/LaTeX mode, whenever a backslash (\) isfound, ispeii skips to 
the next whitespace or TeX/LaTeX delimiter. Certain commands contain arguments that should not be checked, such as 
labels and reference keys found in the \cite command, because they contain arbitrary, nonword arguments Spell checking is 
also suppressed when in math mode. T hus, for example, given 

\chapter {This is a Ckapter} \cite{SCH86} 

ispeii will find "ckapter" but not "sch." The -t option does not recognize theT eX comment character %, so comments are 
also spell checked. It also assumes correct LaT eX syntax. Arguments to infrequently used commands and some optional 
arguments are sometimes checked unnecessarily. The bibliography will not be checked if ispeii was compiled with ignorebib 
defined. Otherwise, the bibliography will be checked but the reference key will not. 

Referencesforthetib(l) bibliography system (text between a [. or<. and .] or .>) will always be ignored in TeX/LaTeX mode. 
The-b and -x options control whether ispeii leavesa backup (.bak) file for each input file. 

T he. bak file containsthe precorrected text. I f there are file opening/writing errors, the. bak file may be left for recovery 
purposes even with the-x option. Thedefault for this option is controlled by the defnobackupflag installation option. 
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The-B and -c options control how ispeii handles run-together words, such as notthe for not the If-Bis specified, such 
words will be considered errors, and ispeii will list variations with an inserted blank or hyphen as possible replacements If 
-c isspecified, run-together words will be considered to be legal compounds so long as both components are in the 
dictionary, and each component is at least as long as a language-dependent minimum (three characters by default). This is 
useful for languages such as German and Norwegian, where many compound words are formed by concatenation. (Note that 
compounds formed from three or more root words will still be considered errors). The default for this option is language 
dependent; in a multilingual installation, the default may vary depending on which dictionary you choose. 

The -p and -m options control when ispeii automatically generates suggested root/affix combinationsfor possible addition to 
your personal dictionary. (These are the entries in the "guess" list that are preceded by question marks.) If -p isspecified, 
such guesses are displayed only if ispeii cannot generate any possibilities that match the current dictionary. If -m isspecified, 
such guesses are always displayed. Thiscan be useful if the dictionary has a limited word list, oraword list with few suffixes. 
However, you should be careful when using this option, as it can generate guesses that produce illegal words The default for 
thisoption iscontrolled by thedictionary file used. 

The-s option suppresses ispeii's normal behavior of sorting the list of possible replacement words. Some people may prefer 
this since it somewhat enhances the probability that the correct word will be low-numbered. 

The-d option is used to specify an alternate hashed dictionary file other than thedefault. If the filename does not contain a 
/, the library directory for the default dictionary file is prefixed; thus, to use a dictionary in the local directory -d ./xxx.hash 
must be used. This is useful to allow dictionaries for alternate languages. Unlike previous versions of ispeii, a dictionary of 
/dev/nuii is illegal because the dictionary contains the affix table. If you need an effectively empty dictionary, create a one- 
entry list with an unlikely string (for example "qqqqq"). 

The-p option is used to specify an alternate personal dictionary file If the filename does not begin with /, $home is prefixed. 
Also, the shell variable wordlist may beset, which renames the personal dictionary in the same manner. The command line 
overrides any wordlist setting. If neither the-p avitch nor the wordlist environment variable is given, ispeii will search fora 
personal dictionary in both the current directory and $home, creating one in $home if none is found. The preferred name is 
constructed by appending .ispeii to the base name of the hash file. For example if you use the English dictionary, your 
personal dictionary would be named .ispeii_engiish. However, if the file .ispeii_words exists, it will be used as the personal 
dictionary regardless of the language hash file chosen. Thisfeature is included primarily for backwards compatibility. 

If the-p option is not specified, ispeii will look for personal dictionaries in both the current directory and the home 
directory. If dictionaries exist in both places, they will be merged. W hen words are added to the personal dictionary, they will 
be written to the current directory if a dictionary already existed in that place; otherwise, they wi II be written to the 
dictionary in the home directory. 

The -w option may be used to specify characters other than alphabeticsthat may also appear in words. For instance -w "&■ 
will allow "AT & T" to be picked up. Underscores are useful in many technical documents. Thereisan admittedly crude 
provision in thisoption for 8-bit international characters Nonprinting characters may be specified in the usual way by 
inserting a backslash followed by the octal character code, for example, \014 for a form feed. Alternatively, if n appears in the 
character string, the (up to) three characters following are a decimal code, 0-255, for the character. For example to include 
bells and form feeds in your words (an admittedly silly thing to do, but aren't most pedagogical examples): 

n007n012 

N umeric digits other than the three following n are simply numeric characters. U se of n does not conflict with anything 
because actual alphabetics have no meaning; alphabeticsare already accepted, ispeii will typically be used with input from a 
file, meaning that preserving parity for possible 8-bit characters from the input text is okay. If you specify the -1 option, and 
actually type text from the terminal, this may create problems if your stty settings preserve parity. 

The -w option may be used to change the length of words that ispeii always accepts as legal. Normally, ispeii will accept all 
one-character words as legal, which is equivalent to specifying -w i. (The default for this avitch is actually controlled by the 
minword installation option, so it may vary at your installation.) If you want all words to be checked against the dictionary, 
regardless of length, you might want to specify -w 0. 0 n the other hand, if your document specifies to accept all words of 
three lettersor less, then regardless of the setting of thisoption, ispeii will only generate words that are in thedictionary as 
suggested replacements for words; this prevents the list from becoming too long. Obviously, thisoption can be very 



ispeii, buildhash, munchlist, findaffix, tryaffix, icombine, ijdn 


dangerous, since short misspellings may be missed. If you use this option a lot, you should probably make a last pass without 
it before you publish your document, to protect yourself against errors 

The -t option is used to specify a default formatter type for use in generating string characters. This switch overrides the 
default type determined from thefilename. The type argument may be either one of the unique names defined in the 
language affix file (such asnroff) or a file suffix including the dot (for example -tex). If no -t option appears and no type 
can be determined from thefilename, the default string character type declared in the language affix file will be used. 

The -l or list option to ispeii is used to produce a list of misspelled words from the standard input. 

The -a option is intended to be used from other programs through a pipe. In this mode, ispeii prints a one-line version 
identification message and then begins reading lines of input. For each input line, a single line iswritten to thestandard 
output for each word checked for spelling on the line. If the word was found in the main dictionary, or your personal 
dictionary, then the line contains only a*. If the word was found through affix removal, then the line contains a+, a space, 
and the root word. If the word was found through compound formation (concatenation of two words, controlled by the-c 
option), then the line contains only a -. 

If the word is not in the dictionary, but there are near misses, then the line contains an &, a space, the misspelled word, a 
space, the number of near misses, the number of characters between the beginning of the line and the beginning of the 
misspelled word, a colon, another space, and a list of the near misses separated by commas and spaces Following the near 
misses (and identified only by the count of near misses), if the word could be formed by adding (illegal) affixes to a known 
root, isa list of suggested derivations again separated by commas and spaces If there are no near misses at all, the line format 
is the same except that the & is replaced by ? (and the near-miss count is always zero). The suggested derivationsfollowing 
the near misses are in the form: 


(for example, "retfry-y-Hes" to get "refries") where each optional pfx and sfx isa string. Also, each near miss or guess is 
capitalized the same as the input word unless such capitalization is illegal: in the latter case each near miss iscapitalized 
correctly according to the dictionary. 

Finally, if the word does not appear in the dictionary, and there are no near misses, then thelinecontainsa#, a space, the 
misspelled word, a space, and the character offset from the beginning of the line Each sentence of text input isterminated 
with an additional blank line indicating that ispeii has completed processing the input line. 

These output lines can be summarized asfollows 
OK: 

Root: + <root> 

Compound: 

Miss: & <original><count><offset>: <miss>, <miss>, .... <guess>, ... 

Guess: ? <original> 0 <offset>: <guess>, <guess>, ... 

N one # <original> <offset> 

For example, a dummy dictionary containing the words fray, Frey, fry, and refried might produce thefollowing response to 
the Command echo 'frqy refries | ispeii -a -m -d ./test.hash: 

(#) International Ispeii Version 3.0.05 (beta), 08/10/91 



This mode is also suitable for interactive use when you want to figure out the spelling of a single word. 

The -a option works just like -a, except that if a line begins with the string "&inciude Fiie&", the rest of the line is taken as 
the name of a file to read for further words. I nput returns to the original file when the include file is exhausted. I ndusion 
may be nested up to five deep. The key string may be changed with the environment variable include_string (the amper¬ 
sands, if any, must be included). 
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When in the-a mode, ispeii will also accept lines of single words prefixed with any of the following: *, &, @, +, %, 

orA line starting with * tells ispeii to insert the word into the user's dictionary (similar to the i command). A line 
starting with & tells ispeii to insert an all-lowercase version of the word into the user's dictionary (similar to theu com¬ 
mand). A line starting with @causes ispeii to accept this word in the future (similar to the a command). A line starting with 
+, followed immediately by tex or nroff, will cause ispeii to parse future in put according the syntax of that formatter. A line 
consisting solely of a+ will place ispeii in TeX/LaTeX mode (similar to the -t option) and - returns ispeii to nroff/troff 
mode (but these commands are obsolete). H owever, string character type is not changed; the ■ command must be used to do 
this A line starting with - causes ispeii to set internal parameters (in particular, the default string character type) based on 
thefilename given in the rest of the line (A file suffix is sufficient, buttheperiod must be included. Instead of afilename or 
suffix, a unique name, as listed in the language affix file, may be specified.) However, the formatter parsing is not changed; 
the + command must be used to change the formatter. A line prefixed with # will cause the personal dictionary to be saved. A 
line prefixed with i will turn on terse mode (explained later in this subsection), and a line prefixed with % will return ispeii 
to normal (non-terse) mode. Any input following the prefix characters+, -, #, i, or % is ignored, as is any input following the 
filename on a ■ line. To allow spell checking of lines beginning with these characters, a line starting with * has that character 
removed before it is passed to the spell checking code. It is recommended that programmatic interfaces prefix every data line 
with an up arrow to protect themselves against future changes in ispeii. 

To summarize these: 

* Add to personal dictionary 

@ Accept word, but leave out of dictionary 

# Savecurrent personal dictionary 
Set parameters based on filename 

+ EnterT eXmode 

Exit TeX mode 
i Enter terse mode 

% Exit terse mode 

Spell check rest of line 

In terse mode, ispeii will not print lines beginning with *, +, or-, all of which indicate correct words. Thissignifi cantly 
improves running speed when the driving program is going to ignore correct words anyway. 

The -s option isonly valid in conjunction with the -a or -a options, and only on BSD-derived systems. If specified, ispeii 
will stop itself with a sigtstp signal after each lineof input. It will notread more input until it receivesasiGCONT signal. This 
may be useful for handshaking with certain text editors. 

The-f option isonly valid in conjunction with the-a or -a options. If -f isspecified, ispeii will write its resultsto the 
given file rather than to standard output. 

The -v option causes ispeii to print its current version identification on the standard output and exit. If the switch is 
doubled, ispeii will also print the options that it was compiled with. 

T he -c, -e [ i - 4 ], and -d options of ispeii are primarily intended for use by the munchiist shell script. T he -c switch causes a 
list of words to be read from the standard input. For each word, a list of possible root words and affixes will be written to the 
standard output. Some of the root words will be illegal and must be filtered from the output by other means; the munchiist 
script does this Asan example, thecommand 

echo BOTHER | ispeii -c 

produces 

BOTHER BOTHE/R BOTH/R 

The-e switch is the reverse of -c; it expands affix flags to produce a list of words For example, thecommand 

echo BOTH/R | ispeii -e 

produces 


BOTH BOTHER 
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An optional expansion level can also be specified. A level of 1 (-ei) isthesameas-e alone. A level of 2 causes theoriginal 
root/affix combination to be prepended to the line: 

BOTH/R BOTH BOTHER 

A level of 3 causes multiple lines to be output, onefor each generated word, with theoriginal root/affix combination 
followed by the word it creates: 

BOTH/R BOTH 
BOTH/R BOTHER 

A level of 4 causes a floating-point number to be appended to each of the level 3 lines, giving the ratio between the length of 
the root and the total length of all generated words including the root: 

BOTH/R BOTH 2.500000 
BOTH/R BOTHER 2.500000 

Finally, the -o flag causes the affix tables from the dictionary fileto be dumped to standard output. 

Unless your system administrator has suppressed thefeature to save space, ispeii is aware of the correct capitalizations of 
words in the dictionary and in your personal dictionary. As well as recognizing words that must be capitalized (such as 
George) and words that must be all capitals (such asNASA), it can also handle words with unusual capitalization (for 
example, IT-Corp or TeX). If a word is capitalized incorrectly, the list of possibilities will include all acceptable capitaliza¬ 
tions. (M ore than one capitalization may be acceptable; for example, my dictionary lists both ITCorp and ITcorp.) 

Normally, thisfeature will not cause you surprises, but there is onecircumstance you need to be aware of. If you useitoadd 
a word to your dictionary that is at the beginning of a sentence (for example the first word of this paragraph if normally were 
notin the dictionary), it will be marked as "capitalization required." A subsequent usage of this word without capitalization 
will be considered a misspelling by ispeii, and it will suggest the capitalized version. You must then compare the actual 
spellings by eye, and then type i to add the uncapitalized variant to your personal dictionary. You can avoid this problem by 
using u to add theoriginal word, rather than i. 

The rules for capitalization are as follows: 

1. Any word may appear in all capitals, as in headings. 

2. Any word that is in the dictionary in all lowercase form may appear either in lowercase or capitalized (as at the 
beginning of a sentence). 

3. Any word that has unusual capitalization (that is, it contains both cases and there is an uppercase character besides the 
first) must appear exactly as in the dictionary, except as permitted by rule 1. If the word is acceptable in all lowercase it 
must appear thus in a dictionary entry. 

buildhash 

The buildhash program builds hashed dictionary files for later use by ispeii. The raw word list (with affix flags) isgiven in 
diet-me, and the affix flags are defined by affix-me. The hashed output is written to hash-file. The formats of the two 
input files are described in ispeii(4). The-s (silent) option suppresses the usual status messages that are written to the 
standard error device. 

munchlist 

Themunchiist shell script is used to reduce the size of dictionary files, primarily personal dictionary files. It is also capable of 
combining dictionaries from various sources. The given files are read (standard input if no arguments are given), reduced to 
a minimal set of roots and affixes that will match thesame list of words, and written to standard output. 

Input for munchlist contains of raw words (such as those from your personal dictionary files) or root and affix combinations 
(probably generated in earlier munchlist runs). Each word or root/affix combination must be on a separate line. 

The -d (debug) option leaves temporary files around under standard names instead of deleting them, so that the script can be 
debugged. W arning: This option can eat up an enormous amount of temporary file space. 

The-v (verbose) option causes progress messages to be reported to stderr so you won't get nervous that munchlist has hung. 
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If the -s (strip) option isspecified, words that are in the specified hash-file are removed from the word list. Thiscan be 
useful with personal dictionaries. 

The-lean be used to specify an alternate affix-me for munching dictionaries in languages other than English. 

The -c option can be used to convert dictionaries that were built with an older affix file without risk of accidentally 
introducing unintended affix combinations into the dictionary. 

T he -t option allows dictionaries to be converted to a canonical string-character format. The suffix specified is looked up in 
the affix file (-1 switch) to determine the string-character format used for the input file; theoutput always usesthecanonical 
string-character format. For example a dictionary collected from T eX source files might be converted to canonical format by 
specifying -t tex. 

The -w option ispassed on to ispeii. 
findaffix 

Thefindaffix shell script is an aid to writers of new language descriptions in choosing affixes. The given dictionary files 
(standard input if none are given) are examined for possible prefixes (-p switch) or suffixes (-s switch, the default). Each 
commonly occurring affix is presented along with a count of the number of times it appears and an estimate of the number 
of bytes that would be saved in a dictionary hash file if it were added to the language table. 0 nly affixes that generate legal 
rootsffound in theoriginal input) are listed. 

If the -c option is not given, theoutput lines arein the following format: 
st rip/add/count/bytes 

where strip isthe string that should be stripped from a root word before adding the affix, add isthe affix to be added, count 
isacount of thenumber of times that this strip/add combination appears, and bytes isan estimate of the number of bytes 
that might be saved in the raw dictionary file if this combination is added to the affix file The field separator in theoutput 
will be the tab character specified by the -t switch; the default is a slash (/). 

If the -c (clean output) option is given, the appearance of theoutput is made visually cleaner (but harder to post process) by 
changing it to 

-strip+add<tab>count<tab>bytes 

where strip, add, count, and bytes areas before, and <tab> represents the ASCI I tab character. 

The method used to generate possible affixes will also generate longer affixes which have common headers or trailers For 
example, thetwo words moth and mother will generate not only the obvious substitution +er but also -h+her and -th+ther 
(and possibly even longer ones depending on the value of min). T0 prevent cluttering the output with such affixes, any affix 
pair that shares a common header (or, for prefixes, trailer) string longer than eiim characters (default 1) will be suppressed. 
You may want to set eiim to a value greater than 1 if your language has string characters usually, the need for this parameter 
will become obvious when you examine the output of your findaffix run. 

N ormally, the affixes are sorted according to the estimate of bytes saved. T he -f switch may be used to cause the affixes to be 
sorted by frequency of appearance. 

To save output file space, affixes which occur fewer than 10 times are eliminated; this limit may be changed with the-i 
switch. T he -m switch specifies a maximum affix length (default a). Affixes longer than this will not be reported. (Thissaves 
on temporary disk space and makes the script run faster.) 

Affixes which generate stems shorter than three characters are suppressed. (A stem is the word after the strip string has been 
removed, and before the add string has been added.) This reduces both the running time and the size of the output file. This 
limit may be changed with the -m switch. The minimum stem length should only beset to 1 if you have a lot of free time 
and disk space (in therangeof many days and hundredsof megabytes). 

Thefindaffix script requires a nonblank field-separator character for internal use Normally, this character is a slash (/), but 
if the slash appears as a character in the input word list, a different character can be specified with the-t switch, 
ispeii dictionaries should be expanded before being fed to findaffix; in addition, characters that are not in the English 
alphabet (if any) should be translated to lowercase. 
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tryaffix 

The tryaffix shell script is used to estimatethe effectiveness of a proposed prefix (-p switch) or suffix (-s switch, the default) 
with a given expanded-file. Only one affix can be tried with each execution of tryaffix, although multi pie arguments can be 
used to describe varying forms of thesame affix flag (for example, theD flag for English can add either d or ed depending on 
whether a trailing E isalready present). Each word in the expanded dictionary that ends (or begins) with the chosen suffix (or 
prefix) has that suffix (prefix) removed; the dictionary is then searched for root words that match the stripped word. Nor¬ 
mally, all matching roots are written to standard output, but if the -c (count) flag is given, only a statistical summary of the 
results is written. The statistics given areacountof words the affix potentially applies to and an estimate of the number of 
dictionary bytes that a flag using the affix would save The estimate will be high if the flag generates words that are currently 
generated by other affix flags (for example in English, bathers can be generated by either bath/x or bather/s). T hediction- 
aryfile, expanded-me, must already be expanded (using the -e switch of ispeii) and sorted, and things will usually work 
best if uppercase has been folded to lower with tr. 

The affix arguments are things to be stripped from the dictionary file to produce trial roots: for English, con (prefix) and ing 
(suffix) are examples The addition parts of the argument are lettersthat would have been stripped off the root before adding 
the affix. For example, in English the affix ing normally strips e for words ending in that letter (for example like becomes 
liking), so we might run 

tryaffix ing ing+e 

to cover both cases 

All of the shell scripts contain documentation as commentary at the beginning; sometimes these comments contain useful 
information beyond the scope of this manual page. 

It is possible to install ispeii in such away as to only support ASCII range text if desired, 

icombine 

T he icombine program is a helper for munchlist. 11 reads a list of words in dictionary format (roots plus flags) from the 
standard input, and produces a reduced list of standard output that combines common roots found on adjacent entries. 
Identical rootsthat have differing flags will have their flags combined, and rootsthat have differing capitalizationswill be 
combined in a way that only preserves important capitalization information. The optional aft-me specifies a language file 
that defines the character sets used and the meanings of the various flags The -t switch can be used to select among 
alternative string character types by giving a dummy suffix that can be found in an aitstringtype statement. 

ijoin 

Theijoin program is a reimplementation of join(l), which handles long lines and 8-bit characters correctly. The-s switch 
specifies that the sort(l) program used to prepare the input to ijoin uses signed comparisonson 8-bit characters; the-u 
switch specifies that sort(l) uses unsigned comparisons All other options and behaviors of join(l) are duplicated as exactly 
as possible based on the manual page, except that ijoin will not handle newline as a field separator. Seethe join(l) manual 
page for more information. 

ENVIRONMENT 

dictionary D efault dictionary to use if no -d flag is given 
wordlist Personal dictionary filename 

include_string C ode for file inclusion underthe-A option 
tmpdir Directory used for some of munchiist'sternporary files 

FILES 

i! libdir ! i /! i defhash! ! Hashed dictionary (may be found in some other local directory, depending on the 

system) 

! ! LIBDIR !! /!! DEFLANG !! Affix-definition file for munchlist 

/usr/dict/web 2 or /usr/dict/words For the Lookup function (depending on thewoRDS compilation option) 

User's private dictionary 

.ispeii_hashfiie D i rectory-spedfic private dictionary 
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SEE ALSO 

spell(l), egrep(l), look(l), join(l), sont(l), sq(lL), tib(lL), ispell(4L), english(4L) 

BUGS 

It takes several to many seconds for ispeii to read in the hash table, depending on size. 

When all options are enabled, ispeii may take several seconds to generate all the guesses at correctionsfor a misspelled word; 
on slower machines thistime is long enough to be annoying. 

The hash table is stored as a quarter-megabyte (or larger) array, so a PD P-11 or 286 version does not seem likely, 
ispeii should understand moretroff syntax, and deal more intelligently with contractions 

Although small personal dictionaries are sorted before they are written out, the order of capitalizations of the same word is 
somewhat random. 

When the-x flag is specified, ispeii will unlink any existing BAK file. 

There are too many flags, and many of them havenon-mnemonic names. 

munchiist does not deal very gracefully with dictionaries that contain nonword characters Such characters ought to be 
deleted from the dictionary with a warning message, findaffix and munchiist require tremendous amounts of temporary file 
space for large dictionaries. They do respect the tmpdir environment variable so this space can be redirected. H owever, a lot 
of the temporary space needed isfor sorting, so tmpdir isonly a partial help on systems with an uncooperative sort(l). 
(Cooperative is defined as accepting the undocumented -t switch). At its peak usage, munchiist takes 10 to 40 times the 
original dictionary's size in kilobytes (The larger ratio isfor dictionaries that already have heavy affix use such as the one 
distributed with ispeii). munchiist is also very slow; munching a normal-sized dictionary (15KB roots, 45KB expanded 
words) takes around an hour on a small workstation. (M ostof thistimeisspent in sort(l), and munchiist can run much 
faster on machines that have a more modern sort that makes better use of the memory avail able to it.) findaffix iseven 
worse; the smallest English dictionary cannot be processed with this script in a mere 50KB of free space, and even after 
specifying switches to reduce thetemporary space required, the script will run for more than 24 hours on a small worksta¬ 
tion. 

AUTHORS 

Pace W i llisson (pace@mit-vax), 1983, based on the P DP-10 assembly version. That version was written by R. E. Gorin in 
1971, and later revised by W. E. M atson (1974) and W. B. Ackerman (1978). Collected, revised, and enhanced for the 
Usenet by Walt Buehring, 1987. Table-driven multilingual version by Geoff Kuenning, 1987-88. Large dictionaries 
provided by Bob Devine (vianet idevine). A complete list of contributorsistoo large to list here, but isdistributed with the 
ispeii sources in thefile Contributors. 

VERSION 

The version of ispeii described by this manual page is International Ispeii version 3.1.00, October 8,1993. 

join 

join— Join lines of two files on a common field 

SYNOPSIS 

join [-a 112] [-v 1]2] [-e empty-string] [-0 field-list...] [-t char] 

]-j [1 12] field] [-1 field] [-2 field] f i I el f i I e2 
join {--help,--version} 

DESCRIPTION 

This manual page documents the GN U version of join, join prints to the standard output a line for each pair of input lines, 
one each from f i i e 1 and f i i e 2 , that have identical join fields. Either filename (but not both) can be-, meaning the standard 
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input, fi i ei andf ii e 2 should be already sorted in increasing order (not numerically) on the join fields; unless the-t option 
is given, they should be sorted ignoring blanks at the start of the line, assort does when given the-b option. 
Thedefaultsarethefollowing: The join field isthefirst field in each line; fields in the input are separated by oneormore 
blanks, with leading blankson theline ignored; fields in the output are separated by a space; each output line consists of the 
join field, the remaining fields from fi i ei, then the remaining fields from fi i e 2 . 


OPTIONS 

-a file-number 

-e string 
-1, -jl field 
-2, -j2 field 
-j field 

-o field-list... 


Print a linefor each unpairable line in file file-number (either 1 or 2), in addition to the normal 
output. 

Replace empty output fields (those that are missing in the input) with string. 

J oin on field field (a positive integer) of file 1. 

Join on field field (a positive integer) of file 2. 

EquivalenttO-1 field -2 field. 

Construct each output line according to theformat in field-list. Each element in field-list 
consists of a file number (either 1 or 2), a period, and afield number (a positive integer). The 
elements in the list are separated by commas or blanks M ultiple field-list arguments can be 
given after a single-0 option; the values of all lists given with -0 are concatenated together. 

Use character char as the input and output field separator. 

Print a linefor each unpairable line in file file-number (either 1 or 2), instead of the normal output. 


In addition, when GNU join is invoked with exactly one argument, thefollowing options are recognized: 

- - help Print a usage message on standard output and exit successfully. 

- -version Print version information on standard output, then exit successfully. 

GNU Text Utilities 


kill 

kill— Terminate a process 

SYNOPSIS 

kill [ -s signal | -p ] [-a]pld ... 
kill -1 [ signal ] 

DESCRIPTION 

kin sends the specified signal to the specified process. If no signal isspecified, theTERM signal issent. The term signal will kill 
processes that do not catch this signal. For other processes, if may be necessary to usetheKiu_(9) signal because this signal 
cannot be caught. 

Most modern shells have a built-in kill function. 

OPTIONS 

pid ... Specify the list of processes that mi should signal. Each pid can be a process ID , or a process name 
-s Specify thesignal to send. The signal may be given as a signal nameor number. 

-p Specify that km should only print the process ID (pid) of the named process, and should not send it a signal. 

-1 Print a list of signal names. These are found in /usr/inciude/iinux/signai.h. 

SEE ALSO 

bash(l), tcsh(l), kill(2), sigvec(2) 
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AUTHOR 

T aken from BSD 4.4. The ability to translate process names to process ids was added by Salvatore Valente 

(<svalente@mit.edu>). 

Linux Utilities 14 October 1994 


killall 

kiiiaii— Kill processes by name 

SYNOPSIS 

killall [-iv] [-signal ] name ... 
killall [-1] 

DESCRIPTION 

kiiiaii sendsasignal to all processes running any of the specified commands. If no signal name is specified, sigterm issent. 
Signals can be specified either by name (for example -hup) or by number (for example, -i). Signal ^ (check if a process exists) 
can only be specified by number. 

If the command name contains a slash (/), processes executing that particular filewill deselected for killing, independent of 
their name. 

kiiiaii returns a nonzero return code if no process has been killed for any of the listed commands. If at least one process has 
been killed for each command, kiiiaii returns zero. 

A kiiiaii process never kills itself (but may kill other kiiiaii processes). 

OPTIONS 

-i Interactively ask for confirmation of killing. 

-l List all known signal names 
-v Report if thesignal wassuccessfully sent. 

FILES 

/proc Location of the proc filesystem 

KNOWN BUGS 

Killing by file only works for executables that are kept open during execution; that is impure executables can't be killed this 
way. 

AUTHOR 

Werner Almesberger(aimesberMi.epfi.ch) 

SEE ALSO 

kill(l), fuser(l), ps(1), kill(2) 

Linux, 11 October 1994 


ksyms 

ksyms- Shows the exported kernel symbols 

SYNOPSIS 

ksyms [-a][-h][-m] 
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DESCRIPTION 

ksyms shows information about all exported kernel symbols. The format is 
The describing header can be turned off with the option -h. 

Normally, only the symbols defined by the loaded modules are shown, but with the option -a, all exported symbols can be 
seen. 

The information can also be seen in /proc/ksyms. A shell-script version ksyms.sh can be used to get the information from / 
proc/ksyms instead, but this program gets the symbol information directly from the kernel with a system call. 

With the option -m (stands for memory map), you can also see the starting address and the size of the allocated memory for 
every loaded module. 

SEE ALSO 

insmod(l), modprobe(l), depmod(l), rmmod(l), lsmod(l), modules(2) 

HISTORY 

The ksyms command was first conceived by Bjorn Ekwall (bjambiox.se). The -m option was inspired by David Hinds 
(dhinds@allegro.Stanford.edu) 

BUGS 

Ksyms might have some, but they are well hidden.... 

Linux, 14 May 1995 


last 

last- Indicate last logins by user or terminal 

SYNOPSIS 

last [-number ][-f fiI ename ][-t tty][-h host name][-i address ][-1][-y] [name...] 

DESCRIPTION 

Last looks back in the wtmp file, which records all logins and logouts for information about a user, a teletype, or any group of 
users and teletypes Arguments specify names of users or teletypes of interest. If multiple arguments are given, the informa- 
tion that appliesto any of the arguments is printed. For example last root console would list all of root'ssessionsaswell as 
all sessionson the console terminal. Last displays the sessionsof thespecified users and teletypes most recent first, indicating 
the times at which the session began, the duration of the session, and the teletype that the session took place on. If the 
session is still continuing or was cut short by a reboot, last so indicates 
The pseudo-user reboot logs in at reboots of the system. 

Last with no arguments displays a record of all logins and logouts in reverse order. 

If last is interrupted, it indicates how far the search has progressed in «rtmp. If interrupted with a quit signal, last indicates 
how far the search has progressed so far, and the search continues 

OPTIONS 

-number Limitthe number of entries displayed to that specified by number . 

-f filename U se f i i e n a me asthenameof the accounting file instead of /var/iog/wtmp. 

-h hostname List Only loginsfrom host name. 

List only loginsfrom ip address. 


-i IP address 
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-l List IP addresses of remote hosts instead oftruncated hostnames, 

-t tty List only loginson tty. 

-y A Iso report year of dates. 


FILES 

/var/iog/wtmp Login database 

20 March 1992 

lbxproxy 

lbxproxy— LBX proxy server for the X W indow system 

SYNOPSIS 

lbxproxy [:displ aynumber ] [option ...] 

NOTE 

This manual page is not definitive or "official." It is derived from information contained in the readme file in theibx source 

DESCRIPTION 

lbxproxy istheLow Bandwidth X pseudo-server. It runs on the remote side of low bandwidth, high-latency connections, 
such as serial lines and wide area networks. It accepts connectionsfrom X clients at the remote end and forwards them to an 
X server at the local end. The LBX protocol used for the low bandwidth connection includes compression and optimizations 
designed to make effective use of the bandwidth available. The current version of LBX isnot a standard of the X Consor¬ 
tium, and will not be compatible with thefinal version. The current version should be treated as an "alpha" or "prototype" 
for people interested in experimenting with it. 

OPTIONS 

lbxproxy acceptsthefollowing options 

:di spi aynumber lbxproxy runs as the given dispiaynumber, which by default is e. A value different from 0 should be 

used if the host running lbxproxy has a local X display. If multiple lbxproxy servers or other X 
servers are to run simultaneously on a host, each must have a unique display number. (Seethe 
"Display N ames" section of thex(l) manual page to learn howto specify which display number 
clients should try to use) 

-ac D isables host-based access control mechanisms E nables access by any host, and permits any host to 

modify the access control list. Use with extreme caution. This option exists primarily for running 
test suites remotely. 

-display di spi ay-number Sets the name of the X server display that lbxproxy connects to. 

-help Prints a usage message 

-i Causesall remainingcommand-lineargumentsto beignored. 

-to seconds Sets default connection timeout in seconds 

NETWORK CONNECTIONS 

lbxproxy supports client connections via most of the connection types supported bytheX servers. (Refertothexserver(l) 
manual page and hardwarespecific X server manual pages for details) Note that in the current implementation someofthe 
connectionstypes have not been implemented correctly. This mostly applies to System V. 
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EXAMPLES 

To setup lbxproxy, start the X server as usual, and then start the proxy. Theibxproxy is a pseudo-server, so any clients that 
wish to useit need to adjust their display. By default, the proxy will listen on <hostname>:i. This can be changed with the 
:displaynumber argument. 

If the proxy is to be running on a host named sharedhost, connecting to an LBX-capable X server on a desktop machine 

named mydesktop, you could use the following command to start the proxy (which would be known asdisplay sharedhost :7): 

mydesktop% rlogin sharedhost 

sharedhost% lbxproxy -display mydesktop:0 :7 & 

sharedhost% xclient -display sharedhost:7 

If you are running LBX over a term connection between mydesktop and sharedhost, try something like this 
mydesktop% trsh 

sharedhost% tredir -r 6008 6000 

sharedhost% lbxproxy -display sharedhost:8 :7 & 

sharedhost% xclient -display sharedhost:7 

SEE ALSO 

General information: x(l) 

Server-specific man pages Xserver(l), Xdec(l), Xmacll(l), Xsun(l), Xnest(l), Xvfb(l), XF86_Accel(l), XF86_Mono(l), 
XF86_SVGA(1), XF86_VGA16(1), XFree86(l) 

AUTHORS 

The LBX team includes DaveLemke, Dale Tonogai, Keith Packard, Jim Fulton from N CD, and Chris Kanterjiev from 
Xerox. 

X Version 11 Release 6 


Id 

id—TheGNU linker 

SYNOPSIS 

Id [ -o.I output ] .1 objfile . . . .br .RB ['-A out put ] obj fiI e ... 

[ -A architecture ][-b\ i nput-format ][-Bstatic ][-c\ commandfile ] 

I -d|-do|-dp ] 

[ -defsym\ symbol = expression ][-e\ entry ][-F ][-F\ format ][- 
format\ input-format ][-g ][-G size ][- -help ][-i ][-1 ar ][- 
Lsearchdir ] [-M] [-Map mapf i I e ] [-m emul at i on ][-n|-N][- 
noinhibit-exec ][-oformat\ out put - for mat ][-R\ filename ][-relax ] 

[ -r | -Ur][-S ][-s ] [-sort-common][-T\ commandfile ][-Ttext\ 
textorg ][-Tdata\ dataorg ][-Tbss\ bssorg ][-t ][-u\ sym ][-V ][- 
v] [--verbose ][--version ][-warn-common][-warn-once][-X ] 

I -x ] 

DESCRIPTION 

id combines a number of object and archive files relocates their data, and ties up symbol references Often the last step in 
building a new compiled program to run isacall to id. 

id accepts Linker Command Language files to provide explicit and total control over the linking process This man page does 
not describe the command language; seethe id entry in info, or the manual Ld: TheGNU Linker, for full details on the 
command language and on other aspects of theG N U linker. 
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This version of id uses the general-purpose BFD libraries to operate on object files. This allows id to read, combine and 
write object files in many different formats, for example, COFF ora. out. Different formats may be linked together to 
produce any available kind of object file You can use objdump -i to get a list of formats supported on various architectures; 
Seeobjdump(l). 

Aside from its flexibility, theGN U linker is more helpful than other linkers in providing diagnostic information. M any 
linkers abandon execution immediately upon encountering an error; whenever possible id continues executing, allowing 
you to identify other errors (or, in some cases, to get an output file in spite of the error). 

TheGN U linker id ismeant to cover a broad range of situations, and to be as compatible as possible with other linkers. Asa 
result, you have many choices to control its behavior through the command line, and through environment variables. 

OPTIONS 

The pldthora of command-line options may seem intimidating, but in actual practice few of them are used in any particular 
context. For instance, a frequent use of id isto link standard UN IX object files on a standard, supported U NIX system. On 
such a system, this line links a file heiio.o : 

$ Id -o output /lib/crt0.o hello.o -lc 

This tells id to produce a file called output as the result of linking the file /nb/crto.o with heiio.o and the library ubc.a, 
which will comefrom the standard search directories 

The command-line options to id may be specified in any order, and may be repeated at will. For the most part, repeating an 
option with a different argument will either have no further effect or override prior occurrences (those further to the left on 
thecommand line) of an option. 

The exceptions—which may meaningfully be used morethan once-are -a, -b (oritssynonym -format), -defsym, -l, -i, -r, 
and -u. 

The list of object filesto belinked together, shown asobjfiie, may follow, precede or bemixed in with command-line 
options except that an objfiie argument may not be placed between an option flag and its argument. 

Usually the linker is invoked with at least one object file but other forms of binary input files can also be specified with -1, 
-r, and the script command language. If no binary input files at all are specified, the linker does not produce any output, and 
issues the message no input files. 

0 ption arguments must either follow the option letter without intervening whitespace or be given as separate arguments 
immediately following the option that requires them. 

-Aar chi tecture In the current release of id, this option is useful only for the Intel 960 family of architec¬ 

tures. In that id configuration, the architecture argument is one of the two-letter names 
identifying members of the 960 family; the option specifies the desired output target and 
warns of any incompatible instructions in the input files It also modifies the linker's search 
strategy for archive libraries to support the use of libraries specific to each particular 
architecture, by including in the search loop names suffixed with thestring identifying the 
architecture. 

For example, if your id command line included -aca as well as -itry, the linker would look 
(in its built-in search paths, and in any paths you specify with -l) for a library with the 
names 

try 

libtry.a 

tryca 

libtryca.a 

Thefirsttwo possibilities would be considered in any event; the last two are due to the use 

of -ACA. 

Future releases of id may support similar functionality for other architecture families. 
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You can meaningfully use -a morethan onceon a command line, if an architecture family 
allows combination of target architectures; each use will add another pair of name variants 
to search for when -1 specifies a library. 

b i nput-format Specify the binary format for input object files that follow thisoption on thecommand line. 

You don't usually need to specify this, as id isconfigured to expect asa default input format 
the most usual format on each machine, i nput-format is a text string, the name of a partic¬ 
ular format supported bytheBFD libraries 

-format i nput-format 

has the same effect, as does the script command target. 

You may wantto use thisoption if you are linking files with an unusual binary format. You 
can also use -b to switch formats explicitly (when linking object files of different formats), 
by including 

before each group of object files in a particular format. 

The default format is taken from the environment variable gnutarget. You can also define 
the input format from a script, using the command target. 

Bstatic This flag is accepted for command-line compatibility with the SunOS linker, but has no 

effect on id. 

c c o mma n d f i i e D i rects id to read link commands from the file commandf lie. T hese commands wi II 

completely override id'sdefault link format (rather than adding to it); commandf He must 
specify everything necessary to describe the target format. 

You may also include a script of link commands directly in thecommand line by bracketing 
it between { and > characters. 

d, -dc, -dp Thesethreeoptionsareequivalent; multipleformsaresupported for compatibility with 

other linkers U se any of them to make id assign space to common symbols even if a 
relocatable output file is specified (-r). The script command force_common_allocation has 
the same effect. 

defsym symbol = expression Create a global symbol in the output file containing the absolute address given by 

ex pr e s s i o n . You may use thisoption as many times as necessary to define multiple symbols 
in thecommand line. A limited form of arithmetic is supported for the ex pres si on in this 
context; you may give a hexadecimal constant or the name of an existing symbol, or use + 
and - to add or subtract hexadecimal constants or symbols If you need more elaborate 
expressions consider using the linker command language from a script, 
e entry Useentry asthe explicit symbol for beginning execution of your program, rather than the 

default entry point. 

f, -Fformat Some older linkers used thisoption throughout a compilation toolchain for specifying 

object-file format for both input and output object files, id's mechanisms (the -b or -format 
optionsfor input files the target command in linker scriptsfor output files, the gnutarget 
environment variable) are more flexible, but it accepts (and ignores) the -f option flag for 
compatibility with scripts written to call the old linker, 
format i nput-format Synonym for -b i nput-format. 

g Accepted, but ignored; provided for compatibility with other tools. 

g size Set the maximum sizeof objectsto beoptimized usingtheGP register to s i ze under MIPS 

E C 0 F F. I gnored for other object fi le formats 

-help Print a summary of the command-line optionson the standard output and exit. Thisoption 

and - -version begin with two hyphens instead of onefor compatibility with other GNU 
programs The other options start with only one hyphen for compatibility with other 
linkers. 

i Perform an incremental link (sameasoption -r). 
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-Map mapfiI e 


-oformat out put -f or mat 




Add an archive file a r to the list of files to link. Thisoption may be used any number of 
times id will search its path list for occurrences of lib ar . afor every ar specified. 

This command adds path searchdir to the list of pathsthat id will search for archive 
libraries You may use this option any number of times 
The default set of paths searched (without being specified with -l) depends on what 
emulation mode id is using, and in some cases also on how it was configured. The paths 
can also be specified in a link script with thesEARCH_DiR command. 

Print (to the standard output file) a link map— diagnostic in-formation about where 
symbols are mapped by id, and information on global common storage allocation. 

Print to thefile mapf i i e a link map—diagnostic information about where symbols are 
mapped by id, and information on global common storage allocation. 

Emulate the emu i at i on linker. You can list the available emulations with the - -verbose 
option. Thisoption overrides the compiled-in default, which is the system for which you 
configured id. 

Specifies readable and writable text and data sections. If the output format supports 
U N IX-style magic numbers, the output is marked asoMAGic. 

W hen you use the -n option, the linker does not page-align the data segment. 

Sets the text segment to be read-only, and nmagic iswritten if possible 
Normally, the linker will not produce an output file if it encounters errors during the link 
process W ith thisflag, you can specify that you wish the output file retained even after 
nonfatal errors 

output isa name for the program produced by id; if thisoption is not specified, the name 
a.out is used by default. The script command output can also specify the output filename 
Specify thebinary formatfortheoutput object file. You don't usually need to specify this 
as id is configured to produce as a default output format the most usual format on each 
machine, out put ■ f or mat isa text string, the name of a particular format supported by the 
BFD libraries. The script command output_format can also specify the output format, but 
thisoption overrides it. 

Read symbol names and their addresses from fi i e n a me , but do not relocate it or include it in 
theoutput. Thisallows your output file to refer symbolically to absolute locations of 
memory defined in other programs. 

An option with machine-dependent effects. Currently thisoption is only supported on the 
H 8/300. 

On some platforms, use this option to perform global optimizations that become possible 
when the linker resolves addressing in your program, such as relaxing address modes and 
synthesizing new instructions in the output object file. 

On platforms where this is not supported, -relax isaccepted, but hasno effect. 

Generates relocatable output, that is, an output file that can in turn serve as input to id. 

This is often called partial linking. As a side effect, in environments that support standard 
UNIX magic numbers, thisoption also sets the output file's magic number to omagic. Ifthis 
option is not specified, an absolute file is produced. When linking C++programs, this 
option will not resolve references to constructors; -Ur isan alternative 
Thisoption does the same as-i. 

Omits debugger symbol information (but not all symbols) from the output file. 

Omits all symbol information from the output file 

N ormally, when id places the global common symbolsin the appropriate output sections, it 
sorts them by size. First come all the onebyte symbols, then all the two bytes, then all the 
four bytes, and then everything else. Thisisto prevent gaps between symbols due to 
alignment constraints Thisoption disables that sorting. 
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-Tbss org, -Tdata org, 

-Ttext org 

-T c o mma n d f i I e, -Tc o mma n d f i I e 




-■verbose 


-warn-common 


U se org as the starting address for— respecti vely— the bss, data, or the text segment of the 
output file, textorg must be a hexadecimal integer. 

Equivalent to -c comma ndf i i e; supported for compatibility with other tools 
Prints names of input files as id processes them. 

Forces sym to be entered in the output file as an undefined symbol. This may, for example 
trigger linking of additional modules from standard libraries, -u may be repeated with 
different option arguments to enter additional undefined symbols. 

For anything other than C ++ programs, this option is equivalent to -r : it generates 
relocatable output, that is an output file that can in turn serve as input to id. When linking 
C++programs -ur will resolve references to constructors, unlike -r. 

D isplay the version number for id and list the supported emulations. D isplay which input 
files can and can not be opened. 

D isplay the version number for id. 

Display the version number for id and exit. 

W arn when a common symbol is combined with another common symbol or with a symbol 
definition. UNIX linkers allow this somewhat sloppy practice but linkers on some other 
operating systems do not. Thisoption allows you to find potential problems from 
combining global symbols. 

Only warn oncefor each undefined symbol, rather than once per module that refers to it. 

If -s or -s isalso specified, delete only local symbols beginning with l. 

If-sor -s isalso specified, delete all local symbols, not just those beginning with l. 


ENVIRONMENT 

You can change the behavior of id with the environment variable gnutarget. 

gnutarget determines the input-file object format if you don't use -b (or its synonym -format). Its value should beoneofthe 
BFD names for an input format. If there is no gnutarget in the environment, id uses the natural format of the host. If 
gnutar-get is set to default , then BFD attempts to discover the input format by examining binary input files; this method 
often succeeds, but there are potential ambiguities, since there is no method of ensuring that the magic number used to flag 
object-file formats is unique. Flowever, the configuration procedure for BFD on each system places the conventional format 
for that system first in the search-list, so ambiguities are resolved in favor of convention. 


SEE ALSO 

objdump(l); id and binutiis entries in info 

Ld:TheGNU Linker, Steve Chamberlain and Roland Pesch; TheGNU Binary Utilities, Roland FI. Pesch. 


COPYING 

Copyright © 1991,1992 Free Software Foundation, Inc. 

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this 
permission notice are preserved on all copies. 

Permission isgranted to copy and distribute modified versions of this manual under the conditionsfor verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 
Permission isgranted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in theoriginal English. 


Cygn us support, 17 August 1992 
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lispmtopgm 

lispmtopgm— Convert a Lisp M achine bitmap file into PGM format 

SYNOPSIS 

lispmtopgm [M spmf i I e ] 

DESCRIPTION 

lispmtopgm reads a Lisp machine bitmap as input and produces a portable graymap as output. 

This isthefileformat written by the tv:write-bit-array-fiie function onTI Explorer and SymbolicsLisp machines 
M ultiplane bitmaps on Lisp machines are color; buttheiispm image file format does not include a colormap, so it must be 
treated as a graymap instead. This is unfortunate. 

SEE ALSO 

pgmtolispm(l), pgm(5) 

BUGS 

Theiispm bitmap file format is a bit quirky; Usually the image in the file has its width rounded up to the next higher 
multiple of 32, but not always. If the width is not a multiple of 32, we don't deal with it properly, but because of the uspm 
microcode, such arrays are probably not image data anyway. 

Also, the lispm code for saving bitmaps has a bug, in that if you are writing a bitmap that is not mod32 across, the file may be 
up to seven bits too short. T hey round down instead of up, and we don't handle this bug gracefully. 

N o color. 

AUTHOR 

Copyright© 1991 byJamieZawinski andjef Poskanzer. 

6 March 1990 


lkbib 

lkbib— Search bibliographic databases 

SYNOPSIS 

lkbib [ -V 1 [-if i el ds ] [—pf i I e n a me ][-tn ] key ... 

DESCRIPTION 

lkbib searches bibliographic databases for references that contain the keyskey... and prints any references found on the 
standard output, lkbib will search any databases given by -p options, and then a default database The default database is 
taken from the refer environment variable if it is set, otherwise it is 
/usr/dict/papers/Ind. 

For each database filename to be searched, if an index filename, i created by gindxbib(l) exists, then it will be searched 
instead; each index can cover multiple databases. 

OPTIONS 

-v Print the version number. 

-pf i i e n a me Search f i i ename. M ultiple-p optionscan be used. 

- 1 st r i ng When searching files for which no index exists, ignore the contents of fields whose names are in st t i ng. 

-tn Only requirethefirstn characters of keys to be given. Initially n is6. 
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ENVIRONMENT 

refer D efault database 

FILES 

/usr/dict/papers/ind Default database to beused if the REFER environment variable is not set. 
filename, i Index files. 

SEE ALSO 

grefer(l), glookbib(l), gindxbib(l) 

GroffVersion 1.09, 6 August 1992 


In 

in- M ake links between files 

SYNOPSIS 

In [options] source [dest] 

In [options] source... directory 

Options: 

[-bdfinsvF] [-S backup-suffix] [-V {numbered,existing,simple}] 

[--version-control={numbered,existing,simple}] [--backup] [--directory] 
[--force] [--interactive] [--no-dereference] [--symbolic] [--verbose] 

[--suffix=backup-suffix] [--help] [--version] 


DESCRIPTION 

This manual page documents the G N U version of in. If the last argument names an existing directory, in links each other 
given file into a file with the same name in that directory. If only onefile is given, it links that file into the current directory. 
Otherwise, if only two files are given, it links the first onto the second. It is an error if the last argument is not a directory 
and more than two files are given. It makes hard links by default. By default, it does not remove existing files. 


OPTIONS 

-b, --backup 

-d, -F, --directory 

-i, --interactive 
-n, --no-dereference 


-s, --symbolic 
-v, --verbose 


-S, --suffix backup-suffix 


M ake backups of files that are about to be removed. 

Allow the superuser to make hard links to directories 

Remove existing destination files 

Prompt whether to remove existing destination files. 

W hen the specified destination is a symbolic link to a directory, attempt to replace the 
symbolic link rather than dereferencing it to create a link in the directory to which it points. 
This option is most useful in conjunction with --force. 

M ake symbolic links instead of hard links This option produces an error message on 
systems that do not support symbolic links. 

Print the name of each file before linking it. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output then exit successfully. 

The suffix used for making simple backup files can beset with the simple_backup_suffix 
environment variable, which can be overridden by this option. If neither of those is given, 
thedefault is", as it isin Emacs. 
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-v, --version-control The type of backups made can beset with thevERSiON_coNTROL environment variable which 

{numbered,existing,simple} can beoverridden by thisoption. If version_control is not set and this option isnot given, 

the default backup type is existing. T he value of the version_control environment variable 
and the argument to thisoption are liketheG N U Emacs version-control variable they 
also recognize synonyms that are more descriptive. The valid values (unique abbreviations 
are accepted) are the following: 

t or numbered Always make numbered backups 

nil or existing Makenumbered backupsof filesthat already havethem, simple 
backups of the others. 

never or simple Always make simple backups 

GNU FileUtilities 


lndir 

indii — C reate a shadow directory of symbolic links to another directory tree 

SYNOPSIS 

lndir fromdir [todir] 

DESCRIPTION 

indir makes a shadow copy todir of a directory tree fromdir, except that the shadow is not populated with real files but 
instead with symbolic links pointing at the real files in the fromdir directory tree. This is usually useful for maintaining 
source code for different machine architectures You create a shadow directory containing links to the real source which you 
will have usually N FS mounted from a machine of a different architecture, and then recompile it. The object files will be in 
the shadow directory, while the source files in theshadow directory are just symlinksto the real files. 

T his has the advantage that if you update the source, you need not propagate the change to the other architectures by hand 
because all source in shadow directories are symlinksto the real thing: Just cd to theshadow directory and recompile away. 
The todir argument is optional and defaults to the current directory. The fromdir argument may be relative (for example, 

../ sro) and is relative to todir (not the current directory). 

N otethat rcs, sees, and cvs.adm directories are not shadowed. 

If you add files, simply run indir again. Deleting files is a more painful problem; the symlinks will just point into never- 
neverland. 

BUGS 

patch gets upset if it cannot change the files. You should never run patch from a shadow directory anyway. 

You need to use something like this: 

find todir -type 1 -print ] xargs rm 

to dear out all files before you can relink (if fromdir moved, for instance). Something likethis: 
find . \! -type d -print 

will find all filesthat are not directories. 

X Verson 11 Release 6 



logger 


295 


locate 

locate— List files in databases that match a pattern 

SYNOPSIS 

locate [-d path] [--database=path] [--version] [--help] pattern... 

DESCRIPTION 

This manual page documents the GN U version of locate. For each given pattern, locate searches one or more databases of 
filenames and displays thefilenames that contain the pattern. Patternscan contain shell-style metacharacters: *, ?, and n. 
The metacharacters do not treat / or. specially. Therefore, a pattern too*bar can match a filename that contains foo3/bar, 
and apattern *duck* can match afilename that containsiake/. ducky. Patterns that contain meta characters should be quoted 
to protect them from expansion by the shell. 

If a pattern is a plain string— it contains no metacharacters— locate displays all filenames in the database that contain that 
string anywhere. If apattern does contain metacharacters, locate only displays filenames that match the pattern exactly. Asa 
result, patterns that contain meta characters should usually begin with a* and will most often end with one as well. The 
exceptions are patterns that are intended to explicitly match the beginning or end of afilename. 

Thefilename databases contain lists of files that were on the system when the databases were last updated. Thesystem 
administrator can choose the filename of the default database, thefrequency with which the databases are updated, and the 
directories for which they contain entries; see updatedb(lL). 

OPTIONS 

-d path, - -database=pat h Instead of searching the default filename database, search thefilename databases in pat h, 
which is a colon-separated list of database filenames. You can also use the environment 
variable locate_path to set the I i st of database f i I es to search. The option overrides the 
environment variable if both are used. 

Thefilenamedatabaseformat changed starting withGNU find and locate version 4.0 to 
allow machines with different byte orderings to share the databases This version of locate 
can automatically recognize and read databases produced for older versions of G N U locate 
or U N IX versionsof locate or find. 

--help Printasummary of theoptionsto locate and exit. 

--version Print the version number of locate and exit. 

ENVIRONMENT 

locate_path C olon-separated list of databasesto search 

SEE ALSO 

find(lL), locatedb(5L), updatedb(lL), xargs(lL), F/ncf/ngF//eS(onlinein info, or printed) 

logger 

logger- M akeentriesin thesystem log 

SYNOPSIS 

logger [-is] ]-f file] ]-p pri] ]-t tag] [message ...] 

DESCRIPTION 

logger provides a shell command interface to the sysiog(3) system log module. 
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OPTIONS 

-i Log the process ID of thelogger processwith each line 
-s Log the message to standard error, as well asthesystem log. 

■f file Log the specified fi le. 

-p pr i Enter the message with thespecified priority. The priority may be specified numerically or as a facility, level 
pair. For example, -p iocai3.info logs the messaged) as informational level in the local3 facility. The default is 
user.notice. 

-t tag Mark every line in the log with the specified tag. 

message W rite the message to log; if not specified, and the -f flag is not provided, standard input is logged. 

The logger utility exits 0 on success, and >0 if an error occurs. 

EXAMPLE 

logger system rebooted: 

logger -p localO.notice -t HOSTIDM -f /dev/idmc 

SEE ALSO 

syslog(3), syslogd(8) 

STANDARDS 

Theiogger command isexpectedto be compatible with IEEE Std 1003.2 (POSIX). 

BSD 4.3, 6 Junel993 



login 

login- Sign on 

SYNOPSIS 

login [ name ] 

login -h tost name 
login -f name 

DESCRIPTION 

login is used when signing on to a system. It can also be used to avitch from one user to another at any time (M ost modern 
shells have support for this feature built into them, however.) 

If an argument is not given, login prompts for the username 

If the user is not root, and if /etc/noiogin exists, the contents of this file are printed to the screen, and the login istermi- 
nated. This istypically used to prevent logins when thesystem is being taken down. 

If the user is root, then the login must be occurring on a tty listed in /etc/securetty. Failureswill be logged with thesysiog 
facility. 

After these conditions are checked, the password will be requested and checked (if a password is required for this username). 
Ten attempts are allowed before login dies, but after the first three, the response starts to get very slow. Login failures are 
reported via thesysiog facility. Thisfacility isalso used to report any successful root logins 
If the file .hushiogin exists, then a quiet login is performed (this disablesthe checking of thechecking of mail and the 
printing of the last login time and message of the day). Otherwise, if /var/iog/iastiog exists the last login time is printed 
(and the current login is recorded). 
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Random administrative things, such as setting the UID and GID of the tty, are performed. The term environment variable is 
preserved, if it exists; other environment variables are preserved if the -p option is used. Then the home, path, shell, term, 
mail, and logname environment variables are set. path defaults to /usr/iocai/bin:/bin:/usr/bin:. for normal users, and to / 
sbin: /bin: /usr/sbin: /usr/bin for root. Last, if this is not a quiet login, the message of the day is printed and the file with the 
user'snamein /usr/spooi/maiiwill be checked, and a message printed if it has nonzero length. 

The user's shell is then started. If no shell isspecified for the user in /etc/passwd,then /bin/sh is used. If there is no directory 
specified in /etc/passwd, then / is used. (T he home directory is checked for the. hushiogin file described earlier.) 

OPTIONS 

-p U sed by getty(8) to tell login not to destroy the environment. 

-f Used to skip a second login authentication. Thisspecifically does not work for root, and does not appear to work 
well under Linux. 

-h Used by other servers (such asteinetd(8)) to pass the name of the remote host to login so that it may be placed in 
utmp and vrtmp. Only the superuser may use this option. 

FILES 


/var/log/wtmp 

/var/log/lastlog 



/etc/nologin 

/etc/usertty 

.hushiogin 


SEE ALSO 

init(8), getty(8), mail(l), passwd(l), passwd(5), environ(7), shutdown(8) 

BUGS 

Linux, unlike other Draconian operating systems, does not check quotas 

The undocumented BSD -r option is not supported. This may be required by somenogind(8) programs. 

AUTHOR 

Derived from BSD login 5.40 (M ay 9,1989) by M ichael Glad (giad@daimi.dk) for H P-UX Ported to Linux 0.12: Peter 
Orbaek (poe@daimi.aau.dk). 

Linux 0.99,1 February 1993 

look 

look— D isplay lines beginning with a given string 

SYNOPSIS 

look [-dfa] [-t termchar] string [file] 

DESCRIPTION 

The look utility displays any lines in file that contain string as a prefix. As look performs a binary search, the lines in file 
must be sorted. 
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If file is not specified, the file /usr/dict/words is used, only alphanumeric characters are compared, and the case of alphabetic 
characters is ignored. 

OPTIONS 

-d D ictionary character set and order; that is, only alphanumeric characters are compared. 

-f Ignore the case of alphabetic characters. 

-a Use the alternate dictionary /usr/dict/web 2 . 

-t Specify a string termination character; that is, only the characters in string up to and including thefirst 
occurrence of termchar are compared. 

The look utility exits 0 if one or more lines were found and displayed, i if no lines were found, and >1 if an error occurred. 

FILES 

/usr/dict/words T he dictionary 
/usr/dict/web 2 Thealternate dictionary 

SEE ALSO 

grep(l), sort(l) 

COMPATIBILITY 

Theoriginal manual page stated thattabsand blank characters participated in comparisons when the -d option was specified. 
This was incorrect and the current man page matches the historic implementation. 

HISTORY 

look appeared in version 7 AT&T UN IX. 

14Junel993 


lpq 

ipq— Spool queue examination program 

SYNOPSIS 

lpq [-1] [-P printer] [job # ...] [user ...] 

DESCRIPTION 

ipq examines thespooling area used by ipd(8) for printing files on the line printer, and reports the status of the specified jobs 
or all jobs associated with auser. ipq invoked without any arguments reports on any jobs currently in the queue. 

OPTIONS 

-p Specify a particular printer; otherwise the default lineprinter is used (or the value of the printer variable in the 

environment). All other arguments supplied are interpreted as usernames or job numbers to filter out only those 
jobs of interest. 

-l Information about each of thefiles comprising the job entry is printed. N ormally, only as much information as 
will fit on one line isdisplayed. 

For each job submitted—in other words, each time ipr(l) is invoked— ipq reports the user's name current rank in the 
queue the names of files comprising the job, the job identifier (a number that may be supplied to iprm(l) for removing a 
specific job), and the total size in bytes Job ordering is dependent on the algorithm used to scan thespooling directory and is 
supposed to be FIFO (First in First Out). Filenamescomprisingajob may be unavailable (when ipr(l) is used asa sink in a 
pipeline) in which case the file is indicated as (standard input). 
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If lpq warns that there is no daemon present (due to some malfunction, for example), the ipc(8) command can be used to 
restart the printer daemon. 

ENVIRONMENT 

If the following environment variable exists, it is used by lpq: 
printer Specifiesan alternate default printer 

FILES 

/etc/printcap 
/var/spool/* 

/var/spool/*/cf* 

Pa/var/spool/*/lock 
/usr/share/misc/termcap 

SEE ALSO 

lpr(l), lprm(l), lpc(8), lpd(8) 

HISTORY 

lpq appeared in BSD 3. 

BUGS 

Due to the dynamic nature of the information in the spooling directory, lpq may report unreliably. Output formatting is 
sensitive to the line length of the terminal; this can result in widely spaced columns 

DIAGNOSTICS 

Unabletoopen variousfiles. The lock file is malformed. Garbage files when there is no daemon active, butfilesin the 
spooling directory. 

BSD 4.2, 9 May 1991 


To determine printer characteristics 

Thespooling directory, as determined from printcap 

Control files specifying jobs 

The lock file to obtain the currently active job 

For manipulating the screen for repeated display 


lpr 

ipr— Offline print 

SYNOPSIS 

lpr [-P printer] [-# num] [-C class] [-J job] [-T title] [-U user] 

]-i [numcols]] [-1234 font] [-wnum] [-cdfghlnmprstv] [name ...] 

DESCRIPTION 

ipr uses a spooling daemon to print the named files when facilities become available. If no names appear, the standard input 
is assumed. 

Thefollowing single-letter options are used to notify the line printer spooler that thefilesare not standard text files The 
spooling daemon will use the appropriate filters to print the data accordingly. 

-c Thefilesare assumed to contain data produced by cifpiot(l). 

-d Thefilesare assumed to contain data from TeX (DVI format from Stanford). 

-f Use a filter that interprets the first character of each line as a standard FORTRAN carriage control character. 

-g Thefilesare assumed to contain standard plot data as produced by the plot routines (See also plot for the filters 
used by the printer spooler.) 
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-i Use a filter that allows control charactersto be printed and suppresses page breaks 
-n Thefilesare assumed to contain data from ditroff (device independent troff). 

-p U se pr(l) to format the files (equivalent to print). 

-t Thefilesare assumed to contain data from troff ( 1 ) (cat phototypesetter commands). 

-v Thefilesare assumed to contain a raster image for devices like the Benson Varian. 

T hese options apply to the handling of the print job: 

-p Forceoutput to a specific printer. N ormally, the default printer is used (site-dependent), or the value of the 
environment variable printer is used. 

-h Suppress the printing of the burst page. 

-m Send mail upon completion. 

-r Remove the file upon completion of spooling or upon completion of printing (with the-s option). 

-s Use symbolic links. Usually, files are copied to the spool directory. The-s option will usesymiink(2) to link data 
files rather than trying to copy them so large files can beprinted. This meansthe files should not be modified or 
removed until they have been printed. 

The remaining options apply to copies, the page display, and headers 

-# niim Thequantitynumisthenurnberofcopiesdesiredofeachfilenarned. Forexample, 

lpr -#3 foo.c bar.c more.c 

would result in three copies of the file foo.c, followed by three copies of thefile bar.c, and so on. On the 
other hand, 

will give three copies of the concatenation of the files Often a site will disable thisfeature to encourage use 
of a photocopier instead. 

1234 font Specifies a font to be mounted on font position i . The daemon will construct a .raiimag file referencing 
thefont pathname 

-c Ar class J ob classification to use on the burst page. Forexample 


causes the system name-the name returned by hostname(l)-to be replaced on the burst page by EECS, 
and the file foo.c to be printed. 

-j Ar job Jobnametoprintontheburstpage. Normally, thefirst file’s name is used. 

-t Ar title Title nameforpr(l), instead of thefilename 

-u user Usernameto print on the burst page also for accounting purposes. Thisoption isonly honored if the real 

user ID isdaemon (or that specified in the printcap file instead of daemon), and is intended for those 
instances where print filters wish to requeue jobs 

-t numcois The output is indented. If the next argument is numeric numcois, it isused as the number of blanks to be 
printed before each line; otherwise; eight characters are printed. 

-w ns Ar num U ses num asthe page width for pr(l). 

ENVIRONMENT 

If the following environment variable exists it isused by ipr: 

printer Specifiesan alternate default printer 



Personal identification. 
Printer capabilities database 
Line printer daemons 
D irectories used for spooling. 




/var/spool/output/*/cf* D aemon control files. 

/var/spooi/output/*/df* Data files specified in cf files. 

/var/spooi/output/*/tf* Temporary copiesof cf files 

SEE ALSO 

lpq(l), lprm(l), pr(l), symlink(2), printcap(5), lpc(8), lpd(8) 

HISTORY 

Theipr command appeared in BSD 3. 

DIAGNOSTICS 

If you try to spool too large a file it will detruncated, ipr will object to printing binary files If a user other than root prints a 
file and spooling is disabled, ipr will print a message saying so and will not put jobs in the queue. If a connection toipd(l) 
on the local machine cannot be made, ipr will say that the daemon cannot be started. Diagnostics may be printed in the 
daemon's log file regarding missing spool files by ipd(l). 

BUGS 

Fonts for troff(l) and T eX reside on the host with the printer. It iscurrently not possible to use local font libraries. 

BSD 4, 24 July 1991 


lprm 

lprm— Remove jobs from the line printer spooling queue 

SYNOPSIS 

lprm [-P printer] [■ job # ...] [user ...] 

DESCRIPTION 

lprm will removeajob, or jobs, from a printer's spool queue. Since the spooling directory is protected from users, using lprm 
is normally the only method by which a user may removeajob. The owner of a job is determined by the user's login name 
and hostname on the machine where the ipr(l) command was invoked. 

Options and arguments: 

-p printer Specify thequeue associated with a specific printer; otherwise the default printer is used. 

If a single - isgiven, iprm will remove all jobsthat a user owns If the superuser employsthisflag, the spool 
queue will be emptied entirely. 

user Causes iprm to attempt to remove any jobs queued belonging to that user (or users). Thisform of invoking 

iprm is useful only to the superuser. 

job # A user may dequeue an individual job by specifying its job number. Thisnumber may beobtained from 

the ipq(l) program. For example 
Ipq - -1 

1st:ken [job#013ucbarpa] 

(standard input) 100 bytes 

lprm 13 

If neither arguments nor options are given, iprm will delete the currently active job if it is owned by the user who invoked 

lprm. 

iprm announces the names of any files it removes and is silent if there are no jobs in the queue that match the request list, 
iprm will kill off an active daemon, if necessary, before removing any spooling files. If a daemon iskilled, a new oneis 
automatically restarted upon completion of file removals 
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ENVIRONMENT 

If the following environment variable exists, it isutilized byiprm: 

printer If the environment variable printer exists, and a printer has not been specified with the -p option, thedefault 
printer is assumed from printer. 

FILES 

/etc/printcap Printer ch aracteri sti cs f i I e 

/var/spooi/* Spooling directories 

/var/spooi/*/iock Lock file used to obtain the pid of the current daemon and the job number of the currently active 
job 

SEE ALSO 

lpr(l), lpq(l), lpd(8) 

DIAGNOSTICS 

"Permission denied" if the user tries to remove files other than his own. 

BUGS 

Because there are race conditions possi blein the update of theiock file, thecurrently active job may be incorrectly identified. 

HISTORY 

The iprm command appeared in BSD 3.0. 

BSD 4.2, 9 May 1991 

lptest 

lptest- Generate line printer ripple pattern 

SYNOPSIS 

lptest [length] [count] 

DESCRIPTION 

lptest writes the traditional "ripple test" pattern on standard output. In 96 lines, this pattern will print all 96 printable 
ASCII characters in each position. Although originally created to test printers, it is quite useful for testing terminals, driving 
terminal ports for debugging purposes, or any other task where a quick supply of random data is needed. 

The length argument specifies the output line length if the default length of 79 is inappropriate. 

The count argument specifies the number of output lines to be generated if thedefault count of 200 is inappropriate Note 
that if count isto be specified, length must also be specified. 

HISTORY 

lptest appeared in BSD 4.3. 



BSD 4.3, 9 May 1991 
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Is, dir, vdir 

is, dir, vdir— List contents of directories 

SYNOPSIS 

Is [-abcdfgiklmnpqrstuxABCFGLNQRSUXI] [-wools] [-T cols] [-1 pattern] [--all]: 
[--escape] [--directory] [--inode] [--kilobytes] [--numeric-uid-gid] [-no-group] 
[--hide-control-chars] [--reverse] [--size] [--width=cols] [--tabsize=cols] 

[--almost-all] [--ignore-backups] [--classify] [--file-type] [--full-time] 

[--ignore=pattern] [--dereference] [--literal] [--quote-name] [--recursive] 

[-- -sort={none, time, size, extension}] [--format={long, verbose, commas, 
across, vertical, single-column}] [--time={atime, access, use, ctime, status}] 
[--help] [--version] [name...] 


DESCRIPTION 

This manual page documents the GN U version of is. dir and vdir are versions of is with different default output formats. 
These programs list each given fileor directory name Directory contents are sorted alphabetically. For is, files are by default 
listed in columns, sorted vertically, if the standard output isa terminal; otherwise, they are listed one per line For dir, files 
are by default listed in columns, sorted vertically. For vdir, files are by default listed in long format. 


OPTIONS 

-a, --all 
-b, - -escape 


- -full-time 

-k, --kilobytes 

-1, --format=long, 
--format=verbose 


-m, --format=commas 


-q, --hide-control-chars 


List all filesin directories, including all files that start with a period (.). 

Q uote nongraphic characters in filenames using alphabetic and octal backslash sequences 
like those used in C. 

Sort directory contents according to the files' status change time instead of the modification 
time. If the long listing format is being used, print the status change time instead of the 
modification time 

List directories like other files, rather than listing their contents 

Do not sort directory contents; list them in whatever order they are stored on the disk. This 

isthesameasenabling-a and -u and disabling-1, -s, and -t. 

List times in full, rather than using the standard abbreviation heuristics. 

Ignored; for U NIX compatibility. 

Print the index number of each file to the left of the filename. 

If file sizes are being listed, print them in kilobytes Thisoverrides the environment variable 

P0SIXLY_C0RRECT. 

In addition to the name of each file, print thefile type permissions, number of hard links 
owner name, group name size in bytes, and timestamp (the modification time unless other 
times are selected). For files with a time that is more than six months old or more than one 
hour into thefuture the timestamp contains the year instead of thetimeof day. 

List files horizontally, with as many as will fit on each line separated by commas 
List the numeric U ID andGID instead of the names. 

Append a character to each filename indicating thefile type 
Print question marks instead of nongraphic characters in filenames 
Sort directory contents in reverse order. 

Print the size of each file in 1KB blocksto the left of the filename If the environment 
variable posixly_correct isset, 512-byte blocks are used instead. 

Sort directory contents by timestamp instead of alphabetically, with the newest files listed 
first. 

Sort directory contents according to the files' last access time instead of the modification 
time. If the long listing format is being used, print the last access time instead of the 
modification time 
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-x, --format=across, 

- -format=horizontal 
-A, --almost-all 
-B, --ignore-backups 
-C, --format=vertical 
-F, - -classify 


-G, - -no-group 


-N, - -literal 


-R, --recursive 


-X, - -sort=extension 
-1, --format=single-column 


-T, - -tabsize cols 
-I, - -ignore pattern 

--help 


List the files in columns, sorted horizontally. 

List all files in directories, except for'.' and 

Do not list files that end with -, unless they are given on thecommand line. 

List files in columns, sorted vertically. 

Append a character to each filename indicating thefiletype For regular files that are 
executable, append a *. Thefiletype indicators are / for directories, e for symbolic links, | 
for FIFOs, = for sockets, and nothing for regular files 
Inhibit display of group information in a long format directory listing. 

List the files linked to by symbolic links instead of listing the contents of the links. 

Do not quote filenames 

Enclose filenames in double quotes and quote nongraphic characters as in C. 

List the contents of all directories recursively. 

Sort directory contents by file size instead of alphabetically, with the largest files listed first. 
Do not sort directory contents; list them in whatever order they are stored on the disk. This 
option is not called -t because the UN IX is -f option also enables -a and disables-1, -s, 
and -t. 11 seems useless and ugly to group those unrelated things together in oneoption. 
Because this option doesn't do that, it has a different name. 

Sort directory contents alphabetically by file extension (characters after the last period); files 
with no extension are sorted first. 

List onefile per line 

Assume the screen iscois columns wide. The default is taken from the terminal driver if 
possible; otherwise, the environment variable columns is used if it isset; otherwise; the 
default is so. 

Assume that each tab stop iscois columns wide The default is 8 . 

Do not listfileswhosenamesmatch theshell pattern pattern unlesstheyaregiven on the 
command line. As in theshell, an initial period (.) in a filename does not match a wildcard 
at the Start Of pattern. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output then exit successfully. 


BUGS 

On BSD systems, the -s option reportssizesthat are half the correct values for files that are N FS-mounted from FI P-UX 
systems On FI P-UX systems it reportssizesthat are twice the correct values for files that are N FS-mounted from BSD 
systems This is due to a flaw in FI P-UX; it also affectstheH P-UX is program. 

GNU FileUtilities 


lsattr 

isatti — List fileattributeson a Linux second extended filesystem 

SYNOPSIS 

lsattr [ -Radv ] [ files... ] 

DESCRIPTION 

lsattr lists thefiles attri butes on an second extended filesystem. 
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-r Recursively list attributes of directories and their contents. 

-a List all filesin directories, including filesthat start with period (.). 
-d List directories like other files, ratherthan listing thei r contents 
-v List the files version. 


AUTHOR 

isattr has been written byRernyCard(card@masi.ibp.fr),thedeveloperandmaintaineroftheext2 fs, 

BUGS 

There are none :-)■ 

AVAILABILITY 

Isattr isavailablefor anonymous FTP from ftp.ibp.fr and tsx- 11 .mit.edu in /pub/linux/packages/ext 2 fs. 

SEE ALSO 

chattr(l) 

Verson 0.5b, N ovember 1994 


Ismod 

ismod— show the loaded modules 

SYNOPSIS 

DESCRIPTION 

ismod shows information about all loaded modules. Theformat is 

name size [list of referring modules] 
size isin4Kbpages 

This information is a copy of the contents of /proc/moduies. 

SEE ALSO 

insmod(l), modprobe(l), depmod(l), rmmod(l), ksyms(l), modules(2) 

HISTORY 

The module support was first conceived by Anonymous (as far as I know...). Linux version by BasLaarhoven 
(bas@vimec.ni), 0.99.14 version byjon Tombs (jon@gtex 02 .us.es), extended by Bjorn Ekwall (bj 0 m@biox.se). 

BUGS 

ismod might have some, but they are well hidden.... 


Linux, 14 May 1995 
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lynx 

lynx— A general-purpose distributed information browser for the W orld W ide W eb 

SYNOPSIS 

lynx [options] [path or URL ] 

U se lynx -help to display a complete list of current options. 


DESCRIPTION 

lynx is a fully-featured W orld W ide W eb (W W W) client for users running cursor-addressable, character-cell display devices 
(for example, vtlOO terminals, vtlOO emulators running on PCsor M acs, or any other "curses-oriented" display). 11 will 
display H ypertext M arkup Language (HTM L) documents containing links to files residing on the local system, as well as 
files residing on remote systems running Gopher, HTTP, FTP, WAIS, and N NTP servers Current versions of lynx run on 
UN IX and VMS. 

lynx can be used to access information on the W orld W ide W eb, or to build information systems intended primarily for 
local access For example, lynx has been used to build several Campus Wide Information Systems (CW IS). In addition, lynx 
can be used to build systems isolated within a single LAN. 


OPTIONS 


At startup, lynx will load any local file or remote URL specified at the command line. For help with U RLs, press? or h while 
running lynx. Then follow the link titled "Helpon URLs." 


-anonymous 


cache=NUMBER 

ofg=F I LENAME 
child 

display=DI SPLAY 

editor=EDI TOR 

emacskeys 

enable_scrollback 


If theonly argument is -,then lynx expects to receive the arguments from stdin. This isto allow 
for the potentially very long command line that can be associated with the -get_data or -post_data 
arguments. (See entries for each later in this list.) 

U sed to specify the anonymous account. 

Disable kanji code translation when Japanese mode is on. 

Set authorization ID and password for protected documents at startup. 

Use the bookmark page as th e startf i I e The default or command line startfile is still set for the 
M ain screen command, and will be used if the bookmark page is unavailable or blank. 

Toggles scanning of news articles for buried references, and converts them to newslinks Not 
recommended because e-mail addresses enclosed in angle brackets will be converted to false news 
links, and uuencoded messages can be trashed. 

Set the number of documents cached in memory. The default is 10 . 

E nable case-sen si tive stri ng searching. 

Specifies a lynx configuration file other than the default lynx.cfg. 

Exit on left-arrow in startfile, and disable save to disk. 

With -traversal, output each page to afile. With -dump, format output as with -traversal, but to 
Set the display variable for X rexeced programs. 

Dumps the formatted output of the default document or one specified on the command line to 
standard out. This can be used in the following way: lynx -dump http://www.w3.org/defauit.htmi. 
Enable Edit mode using the specified editor (vi, ed, emacs, and so on). 

Enable Emacs-like key movement. 

Toggle compatibility with comm programs' scrollback keys (may be incompatible with some 
packages). 


-error_file=FI LE 

-fileversions 

-force_html 


Define a file where lynx will report HTTP accesscodes. 
Set kanji code to EUC when Japanese mode is on. 

Include all versions of files in local VM S directory listings 
Forces the first document to beinterpreted asHTM L. 






D isable FT P access. 

Send form data from stdin using get method and dump results. 

Send a head request for the mime headers. 

Print this lynx command syntax usage message. 

Toggles use of > or -> as a terminator for comments. 

Set home page separate from start page. 

Toggles inclusion of links for all images 
Sdt the default i ndex fi le to the specified URL. 

T oggles J apanese character translations on or off. 

Starting count for ink#.dat files produced by -crawl. 

D isable U RLsthat point to remote hosts. 

Enable local program execution from local files only (if lynx was compiled with local execution 
enabled). 

Prints the mime header of a fetched document along with its source. 

Toggles minimal versus valid comment parsing. 

Disable directory browsing. 

Disable local program execution (default). 

Disable the link list feature in dumps. 

D isable mailing of error messages to document owners 
Disable print functions 

Prevents automatic redirection and prints a message with a link to the new URL. 

D isable the retrieval status messages 
Force numbering of links 

Send form data from stdin using post method and dump results 
Enable print functions (default). 

Toggles pseudo-ALTsfor inlines with no alt string. 

Restricts access to U RLsin the starting realm. 

Flushes the cache on a proxy server (only the first document affected). 

Allows a list of services to be disabled selectively. The following list is printed if no options are 
specified. 

ail- Restricts all options 

bookmark-D isallow changing the location of the bookmark file. 
bookmark_exec -D isallow execution links via the bookmark file. 

Change_exec_perms— D isallow changing the execute permission on files (but still allow it for 
directories) when local file management isenabled. 

default --Same as command-li ne option -anonymous. D isables default services for anonymous users 
Currently set to all restricted except for the following: inside_teinet, outside_teinet, inside_news, 
inside_ftp, outside_ftp, inside_rlogin, outside_rlogin, jump, mail, and goto. D efaultS are Settable 
Within userdefs.h. 

dired_support— D isallow local file management. 

disk_save—Disallow saving binary files to disk in the download menu. 

downioad-D isallow downloaders in the download menu. 

editor— D isallow editing. 

exec -D isable execution scripts 

exec_frozen--D isallow the user from changing the local execution option. 
fiie_uri— D isallow using goto to go to file: U RLs. 
goto- Disable the g (goto) command. 
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inside_ftp— Disallow FTPsfor people coming from inside your domain, (utmp required for 
selectivity.) 

inside_news- Disallow Usenet news posting for people coming from inside your domain, (utmp 
required for selectivity.) 

inside_riogin— Disallow rloginsfor peoplecoming from inside your domain, (utmp required for 
selectivity.) 

instde_teinet -Disallow Telnetsfor people coming from inside your domain, (utmp required for 
selectivity.) 

jump— Disable the j (jump) command, 
mail— D isable mailing feature 
news_post -Disable Usenet news posting. 
options_save -Disallow Saving options in .lynxrc. 

outside_ftp— Disallow FTPsfor people coming from outside your domain, (utmp required for 
selectivity.) 

outside_news— D isallow U sendt news posting for people coming from outside your domain, (utmp 
required for selectivity.) 

outside_riogin— Disallow rloginsfor people coming from outside your domain, (utmp required for 
selectivity.) 

outside_teinet— D isallow Telndtsfor people coming from outside your domain, (utmp required for 
selectivity.) 

print— D isallow most print options 
shell- D isallow shell escapes and lynxexec or lynxprog goto's. 
suspend-D isallow UNIX Ctrl+Z suspends with escape to shell. 
teinet_port— D isallow specifying a port in Telnet goto's. 

D isable recognition of riogin commands. 

Require .mm browsable files to browse directories 

If enabled, the cursor will not be hidden in the right-hand corner but will instead be positioned at 
the start of the currently selected link. show_cursor isthe default for systems without fancy_curses 
capabilities and the default configuration can be changed in userdefs.h. 

Set kanji code to Shift J IS when Japanese mode is on. 

Works the same as dump but outputs FI T M L source instead of formatted text. 

Disable recognition of Tel net commands. 

T ell lynx what terminal type to assume it's talking to. (T his may be useful for remote execution 
when, for example, lynx connects to a remote TCP/IP port that starts a script that, in turn, starts 
another lynx process) 

Turns on WWW trace mode 

T raverseall HTTP links derived from startfiie. When used with -crawl, each link that begins 
with the same string as startfiie isoutputto afile, intended for indexing. See crawl, announce for 
more information. 

Toggles use of _underline_format in dumps. 

Accept only H TT P U RLs (for validation). Complete security restrictions also are implemented. 
Print version information. 

Enable vi-like key movement. 


COMMANDS 

■ U se U p arrow and D own arrow to scroll through hypertext links 

■ Right arrow or Return will follow a highlighted hypertext link. 

■ Left Arrow will retreat from a link. 
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■ Type h or ? for online help and descriptions of keystroke commands. 

■ Type k for a complete list of the current keystroke command mappings. 


NOTES 

This is the Lynx 2.5 Release for U N *X/VM S. 

If you wish to contribute to the further development of lynx, subscribe to our mailing list. Send e-mail to majordomo@sig.net 
with "subscribe Iynx-dev" as the only linein the body of your message. 

Send bug reports, comments, and suggestionsto iynx-dev@sig.net after subscribing. 

U nsubscribe by sending e-mail to majordomo@sig.net with unsubscribe iynx-dev astheonly line in the body of your message 
Do not send the unsubscribe message to the iynx-dev list itself. 

ACKNOWLEDGMENTS 

lynx has incorporated code from a variety of sources along the way. T he earliest versions of lynx included code from Earl 
Fogel of Computing Services at the U niversity of Saskatchewan, who implemented hyperrez in the U N *X environment. 
hyperrez was developed by N id Larson ofThink.com and served asthemodel for the early versions of lynx. Those versions 
also incorporated libraries from theUN*X Gopher clients devdoped at the University of M innesota, and the later versions of 
lynx rdy on the WWW client library code devdoped by Tim Berners-Lee and theWWW community. Also a special thanks 
to FoteosM acrides, who ported much of lynx to VM S and to everyone on theN et who has contributed to lynx's devdop- 
ment either directly (through comments or bug reports) or indirectly (through inspiration and devdopment of other 
systems). 

AUTHORS 

Lou M ontulli, Garrett Blythe Craig Lavender, M ichad Grobe, Charles Rezac 

Academic Computing Services 

University of Kansas 

Lawrence Kansas66047 

Foteos M acrides 

Worcester Foundation 

Shrewsbury, M assachusetts01545 
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macptopbm 

macptopbm- Convert a M acPaint file into a portable bitmap 

SYNOPSIS 

macptopbm [-extraskip N][macpf i I e] 

DESCRIPTION 

macptopbm reads a M acPaint file as input and produces a portable bitmap as output. 

OPTIONS 

-extraskip This flag is to gdt around a problem with some methods of transferring files from the M ac world to the 

UNIX world. M ost of these methods leave the M ac files alone, but a few of them add the find-erinto data 
onto thefront of theUN IX file. Thismeansan extra 128 bytesto skip over when reading thefile. The 
symptom to watch for is that the resulting PBM file looks shifted to one side. If you get this, try- 
extraskip 128, and if that still doesn't look right, try another value. 

All flags can be abbreviated to thdr shortest unique prefix. 
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SEE ALSO 

picttoppm(l), pbmtomacp(l), pbm(5) 

AUTHOR 

Copyright © 1988 byjef Poskanzer. TheM acPaint-reading code is copyright © 1987 by Patrick J. N aughton 
(naughton@wind.sun.com). 

29 March 1989 


make 

make- GNU make utility to maintain groups of programs 

SYNOPSIS 

make [ -f makefile ] [ option ] ... target ... 

WARNING 

This man page is an extract of the documentation of GN U make. It is updated only occasionally because the G N U project 
does not usenroff. For complete current documentation, refer to the info file make or the D VI file make.dvi, which are 
made from the texinfo Source file make, texinfo. 

DESCRIPTION 

The purpose of the make utility isto determine automatically which pieces of a large program need to be recompiled, and 
issue the commandsto recompile them. Thismanual page describes the GN U implementation of make, which was written by 
Richard Stallman and Roland M cG rath. 0 ur examples show C programs because they are most common, but you can use 
make with any programming language whose compiler can be run with a shell command. In fact, make is not limited to 
programs You can use it to describe any task where some files must be updated automatically from others whenever the 
others change. 

To prepare to use make, you must write a file called the makefile that describes the relationships among files in your program 
and states the commandsfor updating each file In a program, typically, the executable file is updated from object files, 
which are in turn made by compiling source files 

Onceasuitable makefile exists each time you change some source files thissimple shell command: 


suffices to perform all necessary recompilations The make program uses the makefile database and the last-modification times 
ofthefilesto decide which of the files need to be updated. For each of those files, it issues the commands recorded in the 
database. 

make executes commands in the makefile to update one or more target names, where name is typically a program. If no -f 
option is present, make will look for the makefiles GNu-makefiie, makefile, and Makefile, in that order. 

N ormally you should call your makefile either makefile or Makefile. (W e recommend Makefile because it appears promi¬ 
nently near the beginning of a directory listing, right near other important files such as readme.) T hefirst name checked, 
GNUmakefiie, is not recommended for most makefiles You should use this name if you have a makefile that is specific to 
GNU make, and will not be understood by other versions of make. If makefile is-, the standard input is read, 
make updates a target if it depends on prerequisite files that have been modified since the target was last modified, or if the 
target does not exist. 



make 




OPTIONS 

-b, -m These options are ignored for compatibility with other versions of make. 

-c dir Changeto directory di r before reading the makefilesor doing anything else. If multiple -c options are specified, 
each is interpreted relative to the previous one:-c / -c etc is equivalent to -c /etc. This istypically used with 
recursive in vocations of make. 

-d Print debugging information in addition to normal processing. The debugging information says which files are 
being considered for remaking, which filetimes are being compared and with what results, which files actually 
need to be remade which implicit rules are considered and which are applied-everything interesting about how 
make decides what to do. 

-e Give variables taken from the environment precedence over variables from makefiles 
-t file Useme asamakefile 

-i Ignoreall errorsin commands executed to remakefiles. 

-i dir Specifiesa directory di r to search for included makefiles. If several-i optionsare used to specify several directo¬ 
ries, the directories are searched in the order specified. Unlike the arguments to other flags of make, directories 
given with -i flags may come directly after theflag: -idi r is allowed, as well as-i d r .This syntax is allowed for 
compatibility with theC preprocessor's-i flag. 

-j jots Specifiesthe number ofjobs (commands) to run simultaneously. If there is more than one-j option, the last one 
iseffective. If the -j option isgiven without an argument, make will not limit thenumber of jobs that can run 
simultaneously. 

-k Continue as much as possible after an error. Although the target that failed, and those that depend on it, cannot 
be remade, the other dependencies of these targets can be processed all the same 
-l, Specifies that no new jobs (commands) should be started if there are other jobs running and the load average is at 
-l load leastload (a floating-point number). W ith no argument, removes a previous load limit. 

-n Print the commands that would be executed, but do not execute them. 

-o f i i e Do not remake the file me even if it is older than its dependencies, and do not remake anything because of 
changes in fi i e. Essentially, the file is treated as very old and its rules are ignored. 

-p Print the database (rules and variable values) that results from reading the makefiles; then execute as usual or as 
otherwise specified. This also prints the version information given by the -v switch (see below). T o print the 
database without trying to remake any files, use make -p -f/dev/nuii. 

-q Question mode. D o not run any commandsor print anything; just return an exit status that is zero if the specified 
targets are already up-to-date nonzero otherwise. 

-r Eliminate use of the built-in implicit rules Also clear out the default list of suffixes for suffix rules 

-s Silent operation; do not print the commands as they are executed. 

-s C ancel the effect of the -k option. T his is never necessary except in a recursive make where -k might be inherited 

from the top-level make via makeflags or if you set -k in makeflags in your environment. 

-t Touch files (mark them up-to-date without really changingthem) instead of running their commands. Thisis 
used to pretend that the commands were done, in order to fool future invocationsof make. 

-v Print the version of the make program plus a copyright, a list of authors, and a notice that there is no warranty. 

After this information is printed, processing continues normally. To get this information without doing anything 
else, use make -v -f/dev/nuii. 

-w Print a message containing the working directory before and after other processing. T hismay be useful for 
tracking down errors from complicated nests of recursive make commands 
-w me Pretend that the target file hasjust been modified. When used with the-n flag, thisshowsyou what would 
happen if you were to modify that file. W ithout -n, it is almost the same as running a touch command on the 
given file before running make, except that the modification time is changed only in the imagination of make. 

SEE ALSO 

/usr/local/doc/gnumake.dvi 

TheGNU Make Manual 
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BUGS 

See the chapter "Problems and Bugs" inTheGNU MakeManual. 

AUTHOR 

This manual page contributed by Dennis M orse of Stanford University. It has been reworked by Roland M cGrath. 

GNU, 22 August 1989 


makedepend 

makedepend- C reate dependencies in makefiles 

SYNOPSIS 

makedepend [ -Dname=def ][-Dname ][-Iincludedir ][-Yincludedir ][-a ] 

[-fmakefile ][-oobjsuffix ][-pobjprefix ][-sstring ][-wwidth ][-v ][-m ] 

[— otheroptions — ] sourcefile . . . 

DESCRIPTION 

makedepend reads each sourcef i i e in sequence and parses it like a C-preprocessor, processing all #inciude, #define, #undef, 
#ifdef, #ifndef, #endif, #if and #eise directives so that it can correctly tell which #inciude, directives would be used in a 
compilation. Any include, directives can reference files having other #inciude directives, and parsing will occur in these files 
as well. 

Every file that a sourcefile includes, directly or indirectly, is what makedepend calls a dependency. These dependencies are then 
written to a makefile in such awaythatmake(l) will know which object files must be recompiled when a dependency has 
changed. 

By default, makedepend places its output in thefile named makefile if it exists; otherwise, Makefile. An alternate makefile may 
be specified with the-f option. It first searches the makefile for the line 

# DO NOT DELETE THIS LINE — make depend depends on it. 

or one provided with the -s option, as a delimiter for the dependency output. I f it finds it, it will delete everything following 
thistotheend of the makefile and put the output after this line If it doesn't find it, the program will append the string to 
the end of the makefile and place the output following that. For each sourcefile appearing on the command line makedepend 
puts lines in the makefile of theform: 
sourcefile.o: dfile . . . 

where sourcefiie.o isthe name from thecommand line with its suffix replaced with .o, and dfile isa dependency 
discovered in a#inciude directive while parsings our c ef i i e or one of the files it included. 

EXAMPLE 

Normally, makedepend will beused in a makefile target so that typing makedepend will bring the dependencies up-to-date for 
the makefile. For example 

SRCS = filel.c file2.c . . . 

CFLAGS = -0 -DHACK -I../foobar -xyz 
depend: 

makedepend — $(CFLAGS) — $(SRCS) 

OPTIONS 

makedepend will ignore any option that it does not understand so that you may use the same arguments that you would for 
cc(l). 

-Dname=def or Define. This places a definition for name in makedepend's symbol table. Without =def, the symbol becomes 
-Dname defined as i. 



makedepend 


0 


-Iincludedir 

-Yincludedir 

-fmakefile 
-oobjsuffix 

-pobjprefix 



Include directory. This option tells makedepend to prepend inciudedir to its list of directories to search 
when it encounters a #inciude directive Bydefault, makedepend only searches the standard include 
directories (usually /usr/inciude and possibly a compiler-dependent directory). 

Replace all of the standard include directories with the single specified include directory; you can omit the 
inciudedir to simply prevent searching the standard include directories 
Append the dependencies to the end of the file instead of replacing them. 

Filename T hisallows you to specify an alternate makefile in which makedepend can place its output. 

Object file suffix. Some systems may haveobject files whose suffix issomething other than .0. This option 
allows you to specify another suffix, such as .b with -o.b or :obj with -o:obj and so forth. 

0 bject file prefix. T he prefix is prepended to the name of the object file. This is usually used to designate a 
different directory for theobject file. T he default is the empty string. 

Starting string delimiter. This option permits you to specify a different string for makedepend to look for in 
the makefile. 

Line width. Normally, makedepend will ensure that every output line that it writes will be no wider than 78 
characters for the sake of readability. Thisoption enables you to change thiswidth. 

Verbose operation. Thisoption causes makedepend to emit the list of files included by each input file on 
standard output. 

W arn about multiple inclusion. T hisoption causes makedepend to produce a warning if any input file 
includes another file more than once. In previous versions of makedepend, thiswas the default behavior; the 
default has been changed to better match the behavior of the C compiler, which does not consider 
multiple inclusion to bean error. Thisoption is provided for backwards compatibility, and to aid in 
debugging problems related to multiple inclusion. 

If makedepend encounters a double hyphen (--) in the argument list, then any unrecognized argument 
following it will be silently ignored; a second doublehyphen terminates this special treatment. In this way, 
makedepend can be madeto safely ignore esoteric compiler arguments that might normally be found in a 
cflags make macro. (Seethe preceding "Example" section.) All options that makedepend recognizes and that 
appear between the pair of double hyphens are processed normally. 


ALGORITHM 

The approach used in this program enables it to run an order of magnitude faster than any other dependency generator I 
have ever seen. Central to this performance are two assumptions: that all files compiled by a single makefile will be compiled 
with roughly the same -1 and -d options; and that most filesin a single directory will include largely thesamefiles 
Given these assumptions, makedepend expects to be called once for each makefile with all source files that are maintained by 
the makefile appearing on the command line It parses each source and include file exactly once maintaining an internal 
symbol tableforeach. Thus the first file on the command line will take an amount of time proportional to the amount of 
time that a normal C preprocessor takes But on subsequent files, if it encounters an include file that it has already parsed, it 
does not parse it again. 

For example, imagineyou are compiling two files fiiei.c and me 2 .c; they both include the header file header, h, and the 
file header, h in turn includes thefiles def 1 .h and def 2 .h. When you run the command: 
makedepend fiiei.c file2.c 

makedepend will parse fiiei.c and consequently, header, h and then defi.h and def 2 .h. It then decidesthat the dependencies 
forthisfileare 

filel.o: header.h defi.h def2.h 


But when the program parses f iie 2 . c and discovers that it, too, includes header . h , it does not parse thefile, but simply adds 
header, h, defi.h, and def 2 .h to the list of dependencies for file 2 .o. 


SEE ALSO 

cc{ 1), make(l) 



Parti: User Commands 


314 


BUGS 

makedepend parses, but doesnot currently evaluate, theSVR4 #predicate(token-iist) preprocessor expression; such 
expressions are simply assumed to be true. This may cause the wrong #inciude directives to be evaluated. 

Imagine you are parsing two files, saymei.c andfiie 2 .c, and each includes thefile def.h. The list of files that def.h 
includes might truly be different when def.h is included bymei.c than when it is included byme 2 .c. But when 
makedepend arrives at a list of dependencies for a file it iscast in concrete. 

AUTHOR 

Todd Brunhoff, Tektronix, Inc. and M IT Project Athena 

X Version 11 Release 6 


makestrs 

makestrs- M ake string table C source and header(s) 

SYNOPSIS 

makestrs [-f source] [-abioptions ...] 

DESCRIPTION 

The makestrs command creates string table C source files and headers. If -t source is not specified, makestrs will read from 
stdin. TheC source file is always written to stdout. makestrs creates one or moreC header files as specified in the source file. 
Thefollowing options may be specified: -sparcabi, -intelabi, -functionabi, -arrayperabi, and -defaultabi. 

-sparcabi isused on SPARC platforms conforming to the SPARC Compliance Definition, i.e, SVR4/Solaris. 

-intelabi used on Intel platforms conforming to the System V Application Binary Interface (SVR4). 

-eariyR6abi may beused in addition to -intelabi for situations where the vendor wishes to maintain binary compatibility 
between X11R6 public-patch 11 (and earlier) and X11R6 public-patch 12 (and later). 

-functionabi generates a functional application binary interface to the string table This mechanism imposes a severe 
performance penalty and it's recommended that you not use it. 

-arrayperabi results in a separate array for each string. This is the default behavior if makestrs was compiled with - 
darrayperstr (it almost never is). 

-defaultabi forces the generation of the"normal" string table even if makestrs was compiled with -darrayperstr. makestrs is 
almost never compiled with -darrayperstr, so this is the default behavior if no application binary interface (ABI) options are 
specified. 

SYNTAX 

The syntax for string-list file isas follows (items in square brackets are optional): 

#prefix <text> 

#feature <text> 

#externref <text> 

#externdef [<text>] 

[#ctempl <text>] 

#file <filename> 
fftable <tablename> 

[#htempl] <text> 


[#table <tablename> 




mattrib 




#table <tablename> 

...] 

[#flie <filename> 

...] 

You may have one or more#me directives. Each #me may have one or more#tabie directives 
The #prefix directive determines thestring that makestr will prefix to each definition. 

The#feature directive determines the string that makestr will use for the feature-test macro, for example x-stringdefines. 
The#externref directive determines thestring that makestr will use for the extern clause; typically thiswill be extern, but 
Motif wants it to beexternalref. 

The#externdef directive determinesthestring that makestr will use for the declaration; typically, thiswill be the null string, 
and M Otif will useexternaldef(_xmstrings). 

T he #ctmpi directive determines the name of the file used asatemplatefortheC source file that is generated. 

Each #tiie <f i i ename> directive will result in a corresponding header file by that name containing the appropriate definitions 
as specified by command-line options A single C source file containing the declarations for the definitions in all the headers 
will be printed to stdout. 

The #htmpi di recti ve determi nes the name of the file used as a template for the C header file that is generated. 

Each #tabie <t a b i ename> directive will be processed in accordance with the A Bl. On most platforms all tables will be 
catenated into a single table with the name of the first table for that file. To conform to the Intel ABI, separate tables will be 
generated with the names indicated. 

The template files specified bythe#ctmpi and #htmpi directives are processed by copying line for line from the template file 
to the appropriate output file. The line containing the string «<string_table_goes_here»> is not copied to the output file. 
The appropriate data is then copied to the output file and then the remainder of the template file is copied to the output file 

BUGS 

makestrs is not very forgiving of syntax errors. Sometimes you need a trailing space after# directives other times they will 
mess you up. N o warning messages are emitted. 

SEE ALSO 

SPARC Compliance Definition 2.2, SPARC International Inc., 535 M iddlefield Road, Suite 210, Menlo Park, CA 94025 
System V Application Binary Interface, Third Edition, ISBN 0-13-100439-5, UNIX Press, PTR Prentice H all, 113 Sylvan 
Avenue, Englewood Cliffs, NJ 07632 

System V Application Binary Interface, Third Edition, I ntel386 Architecture Processor Supplement, ISBN 0-13-104670-5, 
UNIX Press, PTR Prentice H all, 113 Sylvan Avenue Englewood Cliffs, N J 07632 

System V Application Binary Interface, Third Edition, SPARCArchitecture Processor Supplement, ISBN 0-13-104696-9, 
UNIX Press, PTR Prentice H all, 113 Sylvan Avenue Englewood Cliffs, NJ 07632 

X Version 11 Release 6 


mattrib 

mattrib- C hange MS-DOS file attribute flags 

SYNOPSIS 

mattrib [ -a|+a ][-h|+h ][-r|+r ][-s|+s ] msdosfile [ msdosfiles... ] 
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DESCRIPTION 

mattnb adds attri bute flags to an M S-DOS file (with the+operator) or removes attribute flags (with the - operator), 
mattrib allows thefollowing command-line options: 
a Archive bit. Used by some backup programsto indicate a new file. 

r Read-only bit. Used to indicate a read-only file Files with this bit set cannot be erased by del or modified, 

s System bit. U sed by M S-D 0 S to indicatean operating system file, 

h H idden bit. Used to makefiles hidden from dir. 


SEE ALSO 

mtools(l) 


Local 


mbadblocks 

mbadbiocks- Scan an M S-D OS floppy and mark its unused bad blocks as bad. 

SYNOPSIS 

mbadblocks drive: 

DESCRIPTION 

mbadblocks scansan M S-D OS floppy for bad blocks. All unused bad blocks are marked as such in the FAT. This is intended 
to be used right after mtormat. 11 is not intended to salvage bad disks 

SEE ALSO 

mtools(l) 

BUGS 

This should (but doesn't:-() also try to salvage bad blocksthatarein use by reading them repeatedly, and then mark them 
bad. 

mcd 

mcd — C hange MS-DOS directory 

SYNOPSIS 

mcd [ msdosdirectory ] 

DESCRIPTION 

Without arguments mcd will report the current device and working directory. Otherwise, mcd changes the current device and 
current working directory relative to an M S-D 0 S filesystem. 

The environmental variable mcwd may be used to locate the file where the device and current working directory information is 
stored. The default is $HOME/.mcwd. Information in this file is ignored if the file is more than six hours old. 

M S-D OS subdirectory names are supported with either the / or \ separator. The use of the \ separator or wildcards will 
require the di rectory name to be enclosed in quotes to protect it from the shell, 
mcd returns® on successor i on failure. 


SEE ALSO 

mdir(l) 



BUGS 

UnlikeM S-DOS versionsofCD, mcd can be used to change to another device 
It may be wise to remove old .mcwd files at logout. 

Local 


mcookie 

mcookie— Generate magic cookies for xauth 

SYNOPSIS 

mcookie 


DESCRIPTION 


mcookie generates a 128-bit random hexadecimal number for use with theX authority system. Typical usage: 
xauth add :0 . 'mcookie' 


SEE ALSO 

X(l), xauth(l) 


12 February 1995 


mcopy 

mcopy-Copy M S-DOS files to/from UN IX 

SYNOPSIS 

mcopy [ -tnvmoOsSrRA ] sourcefile targetfile 

mcopy [ -tnvmoOsSrRA ] sourcefile [ sourcefiI es ... ] targetdi rectory 
mcopy [ -tnvm ] MSDOSsourcefiI e 


DESCRIPTION 

mcopy copies the specified file to thenamed file, or copies multiple files to thenamed directory. The source and target can be 
either MS-DOSorUN IX files 

T he use of a drive letter designation on the M S-D 0 S files- a: for example- determines the direction of the transfer. A 
missing drive designation impliesa U NIX file whose path starts in the current directory. If a sourcedrive letter is specified 
with no attached filename (for example, mcopy a: .), all files are copied from that drive. 

If only a single M S-D OS source parameter is provided (for example, mcopy aifoo.exe), an implied destination of the current 
directory (.) isassumed. 

A filenameof - meansstandard input or standard output, depending on its position on the command line, 
mcopy will allow thefollowing command-lineoptions 

t Text file transfer, mcopy will translate incoming carriage return/linefeeds to linefeeds 

n N o warning, mcopy will not warn the user when overwriting an existing file 

v Verbose mode, 

m Preservethefile modification time 

If the target file already exists and the -n option is not in effect, mcopy asks whether to overwrite the file or to rename the new 
file. (Seethe mtoois(l) man pagefordetails.) 
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SEE ALSO 

mtools(l), mread(l), mwrite(l) 

BUGS 

U nlike M S-D O S, the + operator ( append) from M S-D 0 S is not supported. 

Local 


md5sum 

mdssum— Generate/check M D 5 message digests 

SYNOPSIS 

md5sum [-bv][-c [file ] ] 
md5sum file ... 

DESCRIPTION 

mdssum generates and checks M D 5 message digests, as described in RFC-1321. Themessage digest produced can bethought 
of as a 128-bit "signature" of the input file. T ypically, mdssum is used to verify the integrity of files made available for 
distribution via anonymous FTP (for example, announcements for new versionsof irc(l) usually contain M D5 signatures). 

M essage digests for a tree of files can be generated with a command similar to the following: 

find . -type f -print | xargs md5sum 

The output of this command is suitable as input for the -c option. 

OPTIONS 

-c [file] Check message digests. Input is taken from stdin or from the specified file. The input should be in the 
same format as the output generated by mdssum. 

-v Verbose. Print filenames when checking. 

-b Readfilesin binary mode; otherwise; end-of-fi le conventions wi 11 beignored. 

HISTORY 

Themd5sum program was written by Branko Lankester and may be freely distributed. The original source code is in the M IT 
PGP 2.6.2 distribution. Those concerned about the integrity of this version should obtain the original sourcesand compile 
their own version. 

The underlying implementation of Ron Ri vest's M D 5 algorithm was written by Colin Plumb and is in the public domain. 
(Equivalent code is also availablefrom RSA D ata Security, Inc.) 

SEE ALSO 

sum(l), cksum(l), pgp(l) 

Linux 1.0,11 February 1995 


mdel 

mdei — D elate an M S-D 0 S file 

SYNOPSIS 


mdel 



mdir 

DESCRIPTION 

mdei deletes a file on an M S-DOS filesystem, 
mdei will allow the following command-line option: 
v Verbose mode. Echo the filenames as they are processed, 

mdei will ask for verification prior to removing a read-only file. 

SEE ALSO 

mtools(l) 

Local 



mdeltnee 

mdeitree— Remove an M S-D 0 S directory tree 

SYNOPSIS 

mdeitree [ -v ] msdosdi rectory [ msdosdirectories ... ] 

DESCRIPTION 

mdeitree removes a directory and all the files and subdirectories it contains from an M S-D OS filesystem, mdeitree will allow 
thefollowing command-line option: 

v Verbose mode. Displays each file or directory as it is removed. 

An error occurs if the directory does not exist. 

SEE ALSO 

mtools(l), mrd(l) 

Local 


mdir 

mdir- Display an M S-D OS directory 

SYNOPSIS 

mdir [ -w ] msdosdi rectory 

mdir [ -w ][-a ] msdosfile [ msdosfiles... ] 

DESCRIPTION 

mdir displays the contents of an M S-D OS directory, 
mdir will allow thefollowing command-line options 

w Wideoutput. Thisoption will printthefilenamesacrossthepagewithoutdisplayingthefilesizeor creation date, 

a Also list hidden files 

An error occurs if a component of the path is not a directory. 

SEE ALSO 

mtools(l) 


Local 
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merge 

merge- T hree-way file merge 

SYNOPSIS 

merge [ opt i o ns ] fiI el fiI e 2 fiI e 3 

DESCRIPTION 

merge incorporates all changes that lead from f i i e 2 to f i 1 e 3 into f i 1 ei. The result ordinarily goes into f i ei. merge is useful 
for combining separate changes to an original. Supposef i 1 e2 is the original, and both f i 1 ei and f i 1 e 3 are modifications of 
f i 1 e2. Then merge combines both changes 

A conflict occurs if both f i 1 e 1 and f i 1 e 3 have changes in a common segment of lines If a conflict isfound, merge normally 
outputsa warning and brackets the conflict with «««< and »»»> lines. A typical conflict will look like this: 


I i nes in file B 

If there are conflicts the user should edit the result and delete one of the alternatives 

OPTIONS 

-a Output conflicts using the -a style of diff3(l), if supported by diff3. This merges all changes leading from fiie 2 
to fiie3 into fiiei, and generates the most verbose output. 

-e, -e These options specify conflict styles that generate less information than -a. See diff3(l) for details. The default is 
-e. W ith -e, merge does not warn about conflicts. 

-l 1 abei Thisoption may begiven up to three times and specifies labelsto be used in place of the corresponding filenames 
in conflict reports. That is, merge-Lx-L y -lz a b c generates output that looks like it camefrom files x, y,andz 
instead of from files a, b, and c. 

-p Send results to standard output instead of overwriting fiiei. 

-q Q uiet; do not warn about conflicts 
-v Print RCS's version number. 

DIAGNOSTICS 

Exit status iso for no conflicts, 1 for some conflicts 2 for trouble. 

IDENTIFICATION 

Author: Walter F.Tichy. 

M anual Page Revision: 5.7; Release D ate: 1995/06/01. 

Copyright © 1982,1988,1989 Walter F. Tichy. 

Copyright © 1990,1991,1992,1993,1994,1995 Paul Eggert. 

SEE ALSO 

diff3(1), diff(l), rcsmerge(l), co(l) 

BUGS 

It normally does not make sense to merge binary files as if they were text, but merge tries to do it anyway. 

GNU, 1 Junel995 
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mesg 

mesg— D isplay (do not display) messages from other users 

SYNOPSIS 

mesg [n][y] 

DESCRIPTION 

The mesg utility isinvoked by a users to control write access others have to the terminal device associated with the standard 
error output. If write access is allowed, then programssuch astaik(l) andwrite(l) may display messages on the terminal. 

T raditionally, write access is allowed by default. H owever, as users become more conscious of various security risks, there is a 
trend to remove write access by default, at least for the primary login shell. To make sure your ttys are set the way you want 
them to besdt, mesg should be executed in your login scripts 
Options available: 
n Disallows messages 

y Permits messages to be displayed 

If no arguments are given, mesg displays the present message statusto thestandard error output. 

The mesg utility exits with oneofthefollowing values: 

\0 M essages are allowed. 

\ i M essages are not al lowed. 
i An error hasoccurred. 


FILES 

/dev/[pt]ty[pq]? 

SEE ALSO 

biff(l), talk(l), write(l), wall(l), login(l), xterm(l) 

HISTORY 

A mesg command appeared in version 6 AT&T UNIX. 

Linux 1.2,10 March 1995 


mformat 

mformat— Add an M S-D OS filesystem to a low-level formatted disk 

SYNOPSIS 

mformat [ -t tracks ] [ -h heads ] [ -s sectors ] [ -1 volume label ] 

[ -S sizecode ] [ -2 sectors on track 0 ] [ -M software sector size ] 

[ -a Jt-X ][-C ll-H hidden sectors ] drive: 

DESCRIPTION 

mformat adds a minimal M S-D OS filesystem (boot sector, FAT, and root directory) to a disk that has already been formatted 
by a U NIX low-level format. 

The follow options are supported: (Thes, 2 , 1 , and m options may not exist if this copy of mtoois has been compiled without 
the use_ 2 m option). 
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t The number of tracksfnot cylinders). 

h Thenumberof heads(sides). 

s Thenumberof sectors per track. If the 2 m option is given, number of 512-byte sector equivalents on generic tracks 

(that is, not head 0 track). If the 2m option is not given, number of physical sectors per track (which may be bigger 
than 512 bytes). 

1 An optional volume label. 

s ThesizecodeThesizeofthesectoris2 * (stzecode + 7 ). 

2 2m format. The parameter to this option describes the number of sectors on track 0, head 0. This option is 
recommended for sectors bigger than normal. 

1 D on't use a 2m format, even if the current geometry of the disk is a 2m geometry. 

m Software sector size. T his parameter describes the sector size in bytes used by the M S-D 0 S fi lesystem. By default 

it isthephysical sector size. 

a If this option is given, an Atari-style serial number isgenerated. Ataris store their serial number in theOEM label. 

x Formats the disk as an Xdf disk. Xdf disks are used by OS/2. This format can hold 1756Kb, and is faster than the 

equivalent 2 m formats. Thedisk has first to below-level formatted using the xdfcopy utility included in thetdutiis 
package 

c Createsthedisk imagefileto install theM S-D OS filesystem on it. 0 bviously, this is useless on physical devices 

such as floppies and hard disk partitions 

h N umber of hidden sectors. This parameter is useful for formatting hard disk partitions which are not aligned on 

track boundaries (in other words first head of first track doesn't belong to the partition, but containsa partition 
table). In that case the number of hidden sectors is in general the number of sectors per cylinder. This is untested. 

n Serial number. 

To format a disk at a density other than the default, you must supply (at least) those command-line parameters that are 

different from the default. 

Mformat returns0 on successor i on failure. 

SEE ALSO 

mlabel(l) 

BUGS 

Requires a low-level format utility from UNIX. 

D oesn't detect (or record) bad block information. 

Local 



mgrtopbm 

mgrtopbm— Convert an M G R bitmap into a portable bitmap 

SYNOPSIS 

mgrtopbm [mgrfile] 

DESCRIPTION 

mgrtopbm reads an MGR bitmap as input and produces a portable bitmap as output. 

SEE ALSO 

pbmtomgr(l), pbm(5) 
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AUTHOR 

Copyright © 1989 byJef Poskanzer. 


24 January 1989 


mkdir 

mkdii— M ake directories 

SYNOPSIS 

mkdir [-p] [-m mode] [--parents] [--mode=mode] [--help] [--version] dir... 

DESCRIPTION 

This manual page documents the GN U version of mkdir. mkdir creates a directory with each given name By default, the 
mode of created directories is 0777 minus the bits set in theumask. 

OPTIONS 

-m, --mode mode Set the modeof created directories to mode, which issymbolic as in chmod and uses the default mode asthe 
point of departure 

-p, --parents Ensurethat each given directory exists Create any missing parent directories for each argument. Parent 
directories default to theumask modified by u+wx. D o not consider an argument directory that already 
exists to bean error. 

- - help Print a usage message on standard output and exit successfully. 

- -version Print version information on standard output then exit successfully. 

GNU FileUtilities 


mkdirhier 

mkdirhiei — M ake a directory hierarchy 

SYNOPSIS 

DESCRIPTION 

The mkdirhier command creates the specified directories Unlike mkdir, if any of the parent directories of the specified 
directory do not exist, it creates them as well. 

SEE ALSO 

mkdir(l) 

X Version 11 Release 6 


mkfifo 

mkfifo— M ake FIFOs (named pipes) 

SYNOPSIS 

mkfifo ]-m mode] [--mode=mode] [--help] [--version] filename... 
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DESCRIPTION 

This manual page documents the GN U version ofmkfifo. mkfifo creates a FIFO with each given name. By default, the mode 
of created FIFO s is 0666 mi nus the bits set i n the umask. 

OPTIONS 

-m, --mode mode Set the modeof created FI FOsto mode, which issymbolic asin chmod and uses the default mode asthe 
point of departure 

- - help Print a usage message on standard output and exit successfully. 

- -version Print version information on standard output then exit successfully. 

GNU FileUtilities 


mkmanifest 

mkmanifest- C reate a shell script to restore UN IX filenames 


SYNOPSIS 

DESCRIPTION 

nikmanifest creates a shell script that will aid in the restoration of UN IX filenames that got clobbered by the M S-DOS 
filename restrictions MS-DOS filenames are restricted to eight-character names, three-character extensions, uppercase only, 
no device names and no illegal characters 

The mkmanifest program is compatible with the methods used in pcomm, arc, and mtoois to change perfectly good UN IX 
filenames to fit the MS-DOS restrictions. 

EXAMPLE 

Say you want to copy the following UN IX files to an M S-DOS disk (using the mcopy command): 

very_long_name 

illegal: 


Capital 

mcopy will convert the names to 

very_lon 

capital 

The command: 

mkmanifest very_long_name 2.many.dots illegal: good.c prn.dev Capital > manifest 
would produce the following: 
mv very_lon very_long_name 
mv 2xmany.dot 2.many.dots 
mv illegalx illegal: 

mv capital Capital 
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Notice that good, c did not require any conversion, so it did not appear in the output. 

Suppose I've copied these files from thedisk to another UNIX system, and I now want thefiles back to their original names. 
If the file manifest (the output captured above) was sent along with those files, it could be used to convert the filenames 

BUGS 

The short names generated by mkmanif est follow the old convention (from mtoois-2.0.7) and not the one from Windows 95 
and mtoois-3.0. 

SEE ALSO 

arc(l), pcomm(l), mtools(l) 

Local 


mknod 

mknod— M akespecial files 


SYNOPSIS 

mknod [options] filename {bcu} major minor 
mknod [options] filename p 

Options: 

]-m mode] [--mode=mode] [--help] [--version] 


DESCRIPTION 

This manual page documents the GN U version of mknod. mknod creates a FIFO, character special file, or block special file with 
the given filename By default, the mode of created files is 0666 minus the bits set in theumask. 

T he argument after filename specifies the type of file to make: 
p for a FIFO 

b for a block (buffered) special file 
c or u for a character (unbuffered) special file 

When making a block or character special file, the major and minor device numbers must be given after thefile type. 


OPTIONS 

--help 


Sdt the mode of created files to mode, which issymbolic as in chmod and uses the default mode as the point 
of departure. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output then exit successfully. 

GNU File Utilities 


mlabel 

miabei— M akean M S-DOSvolumelabel 

SYNOPSIS 

mlabel [ -v ] drive: [ new_I abeI ] 
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DESCRIPTION 

miabei displays the current volume label, if present. If newj abei isnot given, and if neither thee nor the s options are set, it 
prompts the user for anew volume label. To delete an existing volume label, press return at the prompt, 
miabei supportsthefollowingcommand-lineoption: 

v Verbose mode. D isplay the new volume label if the label supplied is invalid, 

c Clears an existing label, without prompting the user, 

s Shows the existing label, without prompting the user. 

Reasonable care istaken to create a valid M S-D OS volume label. If an invalid label is specified, miabei will change the label 
(and display the new label if the verbose mode is sdt). 

Miabei returns 0 on successor 1 on failure. 


SEE ALSO 

mformat(l) 


Local 


mmd 

mind — M ake an M S-D0 S subdirectory 

SYNOPSIS 

mmd [ -voOsSrRA ] msdosdi rectory [ msdosdirectories... ] 

DESCRIPTION 

mmd makes a new directory on an M S-DOS filesystem. 

mmd will allow thefollowing command-lineoption: 

v Verbose mode. D isplay the new directory nameasit iscreated. 

An error occurs if the directory already exists. 

SEE ALSO 

mtools(l), mrd(l), 

Local 


mmount 

mmount— M ount an M S-D 0 S disk 

SYNOPSIS 

mmount msdosdrive [mountargs] 

DESCRIPTION 

mmount reads the boot sector of an M S-D OS disk, configures the drive geometry, and finally mounts it, passing mountargs to 
mount. If no mount arguments are specified, the name of the device is used. If the disk is write-protected, it is automatically 
mounted read-only. 



SEE ALSO 

mtools(l), mount(8) 


Local 


mmove 

mmove— M oveor rename an existing M S-D OS file or subdirectory 

SYNOPSIS 

mmove [ -voOsSrRA ] sourcefile targetfile 

mmove [ -voOsSrRA ] sourcefile [ sourcefiles... ] targetdirectory 

DESCRIPTION 

mmove moves or renames an existing MS-DOS file or subdirectory. 

mmove will allow thefollowing command-line option: 

v Verbosemode. Display the new filename if the name supplied isinvalid. 

Additionally, it allows the clash-handling options described in the man page for mtoois. 

M S-D OS subdirectory names are supported with either the / or \ separator. The use of the \ separator or wildcards will 
require the names to be enclosed in quotes to protect them from the shell. U nlike the M S-D OS version of move, mmove is able 
to move subdirectories. 

SEE ALSO 

mren(l), mtools(l) 


more 

more- File perusal filter for crt viewing 

SYNOPSIS 

more [-dlfpcsu] [-num] [ + / pattern] [+ linenum] 

DESCRIPTION 

more is a filter for paging through text one screenful at a time. This version is especially primitive. Users should realize that 
iess(l) provides more(l) emulation and extensive enhancements 

OPTIONS 

Command-line options are described in thefollowing list. Options are also taken from the environment variable more (make 
sure to precede them with a hyphen (-)) but command-line options will override them. 

-num Thisoption specifies an integer that is the screen size (in lines). 

-d more will prompt the user with the message [Press space to continue, 'q' to quit.] and will display [Press 1 h 1 

for instructions.] instead of ringing the bell when an illegal key is pressed. 

-l more usually treats (form feed) asa special character, and will pauseafteranylinethatcontainsaformfeed.The-i 
option will prevent this behavior. 

-f C auses more to count logical, rather than screen lines (that is, long lines are not folded). 

-p Do not scroll. Instead, clear the whole screen and then display the text. 

-c Do not scroll. Instead, paint each screen from the top, clearing the remainder of each lineasit isdisplayed. 
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-s Squeeze multiple blank lines into one. 

-u Suppress underlining. 

+/ T he+/ option specifies a string that will be searched for before each file is displayed. 

+num Start at linenumber. 


COMMANDS 

Interactive commands for more are based on vi(l). Some commands may be preceded by a decimal number, called k in the 
following descriptions In thefollowing descriptions "x means controi-x. 

hor ? Help: display a summary of these commands. If you forget all the other commands remember this one 

space D isplay next k lines of text. D efaultsto current screen size. 

z Display next k lines of text. Defaults to current screen size Argument becomes new default. 

return Display next k lines of text. Defaults to i. Argument becomes new default, 

d or "d Scroll k lines Default is current scroll size initially 11. Argument becomes new default, 

q or Q INTERRUPT Exit. 

s Skipforward k linesof text. Defaultsto i. 

f Ski p forward k screenfuls of text. D efaults to i. 

b or ■ b Ski p backwards k screenfuls of text. D efaults to i. 

1 Go to placewhere previous search started. 

D isplay current line number. 

/pattern Search for kth occurrence of regular expression. D efaults to i . 

n Search for kth occurrence of last r.e. D efaults to i . 

!<cmd> or: !<cmd> Execute <cmd> in a subshell, 
v Start up /usr/bin/vi at current line 

"l Redraw screen. 

:n Go to kth next file Defaultsto i. 

:p Go to kth previousfile. Defaultsto i. 

ic :f Display current filename and linenumber. 

Repeat previous command. 

ENVIRONMENT 

more utilizes the following environment variables, if they exist: 
more This variable may beset with favored options to more. 

shell C urrent shell in use (normally set by the shell at login time). 

term Specifiesterminal type, used by more to get the terminal characteristics necessary to manipulate the screen. 

SEE ALSO 

vi(l), less(l) 

AUTHORS 

Eric Shienbrood, UC Berkeley. M odified by Geoff Peck, UCB to add underlining, single spacing. M odified byjohn 
Foderaro, UCB to add -c and more environment variable 

HISTORY 

The more command appeared in BSD 3.0. Thisman page documents more version 5.19 (Berkeley 29 Junel988), which is 
currently in usein theLinux community. Documentation was produced using several other versions of the man page, and 
extensive inspection of the source code 


L inux 0.98, 25 D ecember 1992 
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mrd 

nird— Remove an M S-D OS subdirectory 

SYNOPSIS 

mrd [ -v ] msdosdirectory [ msdosdirectori.es... ] 

DESCRIPTION 

mrd removes a directory from an M S-D OS filesystem, mmd will allow thefollowing command-line option: 
v Verbosemode. Display the directory nameasit isremoved. 

An error occurs if the directory does not exist or is not empty. 

SEE ALSO 

mtools(l), mmd(l), mdeltree(l) 

Local 


mread 

mread— Read (copy)an MS-DOSfileto UNIX 

SYNOPSIS 

mread [ -tnvmoOsSrRA ] msdosfile unixfile 

mread [ -tnvmoOsSrRA ] msdosfile [ msdosf i I es ... ] unixdi rectory 

DESCRIPTION 

This command is obsolete, and only supplied for backwards compatibility reasons with old scripts Usemcopy instead. 

SEE ALSO 

mcopy(l), mtype(l), mtools(l) 


mren 

mren- Rename or move an existing M S-DOSfile or subdirectory 

SYNOPSIS 

mren [ -voOsSrRA ] sourcefile targetfile 

mmove [ -voOsSrRA ] sourcefile [ sourcefiles... ] targetdirectory 

DESCRIPTION 

mren renames an existing file on an M S-D 0 S filesystem. 

Mren will allow the following command-line option: 

voOsSrRA Verbosemode. Display the new filename if the name supplied isinvalid. 

If the first syntax is used (only one sourcefile), and if the target name doesn't contain any slashes or colons, the file (or 
subdirectory) will be renamed in the same directory, instead of being moved to thecurrentmed directory as would be the case 
with mmove. U nlike the M S-DO S version of ren, mren can be used to rename directories. 
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BUGS 

Unlike theM S-DOS version of ren, mren can be used to rename directories 

SEE ALSO 

mcd(l) 

Local 


mtest 

mtest— T est the mtoois configuration fi les 

SYNOPSIS 

DESCRIPTION 

mtest reads the mtoois configuration files and prints thecumulative configuration to stdout. The output can be used asa 
configuration file itself (although you might want to remove redundant clauses). You may use this program to convert old- 
style configuration files into new style configuration files 

SEE ALSO 

mtools(5) 

Local 


mtoois 

mtoois— A collection of toolsformanipulating M S-DOSfiles 

SYNOPSIS 

The mtoois are 

mattrib— C hange MS-DOS file attribute flags 

mbadbiocks— T est a floppy disk, and mark the bad blocks in the FAT 

mod- C hange MS-DOS directory 

mcopy-Copy M S-DOS files to/from UN IX 

mdei— D eldte an MS-DOS file 

mdii — D isplay an M S-D0 S directory 

mformat— Add an M S-D OS filesystem to a low-level formatted floppy disk 

miabei- M akean M S-DOSvolumelabel 

mmd — M ake an M S-D 0 S subdirectory 

mmount— M ount an M S-D 0 S disk 

mrd- Remove an M S-D OS subdirectory 

mmove- M oveor rename an M S-D OS fileor subdirectory 

mren- Rename an existing M S-D OS file 

mtype- D isplay contents of an M S-DOS file 

mtest- Test and display the configuration 



DESCRIPTION 

mtoois isa public domain collection of programsto allow UN IX systems to read, write, and manipulate fileson an MS-DOS 
filesystem (typically a floppy disk). Where reasonable, each program attempts to emulate the M S-D OS equivalent command. 
However, unnecessary restrictions and oddities of DOS are not emulated. For instance it is possible to move subdirectories 
from one subdirectory to another. 

M S-D OS filenames are optionally composed of a drive letter followed by a colon, a subdirectory, and a filename. Filenames 
without a drive letter refer to U N IX files. Subdirectory names can use either the / or \ separator. The use of the \ separator 
or wildcards will require the names to be enclosed in quotes to protect them from the shell. (N ote: Wildcards in U NIX 
filenames should not be enclosed in quotes, because here users want the shell to expand them.) 

DIFFERENCESWITH MS-DOS 

The regular expression "pattern matching" routines follow the UN IX-style rules. For example * matches all M S-D OS files 
in lieu of*.*. The archive hidden, read-only, and system attribute bits are ignored during pattern matching. 

All options use the - (minus) flag, not / as you'd expect in M S-DOS. 

M ost mtoois commands allow multiple filename parameters, which doesn't follow M S-D OS conventions, but which is more 
user friendly. 

WORKING DIRECTORY 

Themed command is used to establish the device and the current working directory (relative to the M S-D OS filesystem); 
otherwise the default is assumed to be a : /. However, unlike M S-DOS, there is only one working directory, and not one per 
drive. 

VFAT-STYLE LONG FILENAMES 

This version of mtoois supports VFAT-style long filenames. If a U NIX filename is too long to fit in ashortDOS name, it is 
stored asaVFAT long name, and a companion short name is generated. This short name is what you see when you examine 
the disk with a pre-7.0 version of DO S. The following table shows some examples of short names: 


UNIX Name MS-DOS Name Reason for theChange 


thisisatest THISISAT 

alain.knaff ALAIN.KNA 

.abc X.ABC 

hot+cold HOTXCOLD 


Filename too long 
Extension too long 
PRN isadevicename 
Null filename 
Illegal character 


The initial U N IX-style filename (whether long or short) is also called primary name, and the derived short name is also called 

secondary name 

Example: 

mcopy /etc/motd a:Reallylongname 

mtoois creates a V FAT entry for Reaiiyiongname, and uses reallylo as a short name Reaiiyiongname is the primary name, and 
reallylo is the secondary name 
In this example: 

copy /etc/motd a:motd 

motd fits into the D 0 S filename limits mtoois doesn't need to derivate another name, motd is the primary name, and there is 
no secondary name. 

In a nutshell: The primary name is the long name, if one exists or the short name if there is no long name 
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NAME CLASHES 

When writing a file to disk, its long name (primary name) or short name may collide with an already existing file or 

directory. This may happen for all commands that create new directory entries: mcopy, mind, mren, mmove, mwrite, and mread. 

When a name clash happens, mtoois asks you what it should do. It offers several choices: 

overwrite 0 verwrites the existing file. It is not possible to overwrite a directory with afile. 

rename Renamesthe newly created file mtoois will prompt for the new filename. 

autorename Renamesthe newly created file mtoois will chose a name by itself, without prompting. 

skip G ives up on thisfile and moves on to the next (if any). 

To choose an option, type its first letter at the prompt. If you use a lowercase letter, the option applies for this file only; if 
you use an uppercase letter, theoption applies to all files 

You may also choose options (for all files) on thecommand line when invoking mtoois: 

-o 0 verwrites primary name by default 
-o 0 verwrites secondary names by dtfault 
-r Renames primary name by default 
-r Renamessecondary name by default 

-a Autorenames primary name by default 
-a Autorenames secondary name by default 
-s Skips primary name by default 
-s Skips secondary name by default 

-m Asks user what to do with primary name 

-m Asks user what to do with secondary name 

By default, the user is prompted if the primary name clashes, and the secondary name is autorenamed. 

If a name clash occurs in aUN IX directory, mtoois only asks whether to overwritethefileorto skip it. 

CASE SEN SITIVITY 0 F TH E VFAT FILESYSTEM 

TheVFAT filesystem is able to remember the case of the filenames H owever, filenames that differ only in case are not 
allowed to coexist in the same directory. For example if you store a file called LongFiieName on a VFAT filesystem, mdir will 
show thisfile as LongFiieName, and not as Longtiiename. H owever, if you then try to add LongFiiename to the same directory, 
it will be refused, because caseisignored for clash checks. 

TheVFAT filesystem allows the storing of thecase of afilenamein theattribute byte, if all letters of the filename are the 
same case and if all letters of the extension are the same case too. mtoois uses this information when displaying the files, and 
also to generate the UN IX when mcopyingto aUNIX directory. This may have unexpected results when applied to files 
written usingapre-7.0 version of DOS; indeed, thesefilenamesmapto all uppercase This is different from the behavior of 
the old version of mtoois, which used to generate lowercase UN IX filenames 

XDF DISKS (LINUX ONLY) 

Xdf is a high-capacity format supported by OS/2. It can hold 1,840KB per disc. That's not very high compared to the best 
2m formats but its main advantage is that it is fast: 600 milliseconds per track. That'sfaster than the good old 21 sector 
format, and almost asfast as the standard 18 sector format. In order to access these disks, set theuse_xdf variable for the 
drive. Seemtoois(5) for detailson howto do this. Fast Xdf access is only available for kernels more recent than 1.1.34. 


CAUTION 


Attention distributors If mtoois is compiled on Linux, on a kernel more recent than 1.3.34, it won't run on an older 
kernel. H owever, if it has been compiled on an older kernel, it will still run on a newer kernel, except that Xdf access is 




mtype 


0 


slower. It is recommended that distribution authors only include mtoois binaries compiled on kernels older than 1.3.34 
until 2.0 comesout. W hen 2.0 isout, mtoois binaries compiled on newer kernels may (and should) be distributed, mtoois 
binaries compiled on kernels older than 1.3.34 won't run on any kernel 2.1 or later. 


EXIT CODES 

All the mtoois commands return 0 on success, 1 on utter failure, or 2 on partial failure. All the mtoois commands perform a 
few sanity checks before going ahead, to make sure that the disk is indeed an M S-DOSdisk (asopposed to, say, an ext2 or 
minix disk). These checks may reject partially corrupted disks, which might otherwise still be readable. To avoid these 
checks, set the mtools_skip_check environmental variable 

SEE ALSO 

mattrib(l), mbadblocks(l), mcd(l), mdel(l), mformat(l), mmove(l), mrd(l), mren(l), mtype(l), mcopy(l), mdir(l), mlabel(l), 
mmd(l), mmount(l) 

BUGS 

An unfortunate side effect of not guessing the proper device (when multiple disk capacities are supported) isan occasional 
error message from the device driver. These can be safely ignored. 

The fat checking code chokes on 1.72M B disks mformatted with pre-2.0.7 mtoois. Set the environmental variable 
mtools_fat_compatibility to bypassthefat checking. 

The support for non-Linux OS variants has not been tested fora longtime. It may contain bugs, or even not work at all. 

Local 


mtvtoppm 

mtvtoppm— Convert output from the MTV orPRT ray tracers into a portable pixmap 

SYNOPSIS 

mtvtoppm [ mt v f i I e ] 

DESCRIPTION 

mtvtoppm readsan input filefrom M arkVan DeWettering'sMTV ray tracer and produces a portable pixmap as output. 

The PRT ray tracer also produces thisformat. 

SEE ALSO 

ppm(5) 

AUTHOR 

Copyright © 1989 byjef Poskanzer 

2 February 1989 


mtype 

mtype- Display contents of an M S-DOSfile 

SYNOPSIS 


mtype [ -ts ] 
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DESCRIPTION 

mtype displays the specified M S-DOSfileon thescreen. 
mtype will allow thefollowing command-lineoptions 

t Text file viewing, mtype will translate incoming carriage rdturn/linefeeds to linefeeds 

s Strip high bit. mtype will strip the high bit from the data. 

M S-D OS subdirectory names are supported with either the / or \ separator. The use of the \ separator or wildcards will 
require the names to be enclosed in quotes to protect them from the shell. 

Themed command may be used to establish the device and the current working directory (relative to M S-DOS); otherwise, 
the default isA:/. 

mtype returns 0 on success 1 on utter failure, or 2 on partial failure. 

SEE ALSO 

mcd(l), mread(l) 

BUGS 

Allows multiple arguments which does not follow the M S-D OS convention. 

Local 


mv 

mv— Renamefiles 


SYNOPSIS 

mv [options] source dest 
mv [options] source... directory 

Options: 

[-bfiuv] [-S backup-suffix] [-V {numbered,existing,simple}] [--backup] [--force] 
[--interactive] [--update] [--verbose] [--suffix=backup-suffix] 

[--version-control={numbered,existing,simple}] [ --help] [--version] 


DESCRIPTION 

This manual page documents the G N U version ofmv. If the last argument names an existing directory, mv moves each other 
given file into a file with the same name in that directory. 0 therwise, if only two files are given, it movesthefirst onto the 
second. It is an error if the last argument is not a directory and more than two files are given. It can move only regular files 
across filesystems. If a destination file is unwritable the standard input is a tty, and the-f or - -force option is not given, mv 
prompts the user for whether to overwrite the file If the response does not begin with y or y, thefile is skipped. 


OPTIONS 

-b, --backup 
-i, --interactive 
-u, --update 


--version 


M ake backups of files that are about to be removed. 

Remove existing destination files and never prompt the user. 

Prompt whether to overwrite each destination file that already exists. If the response does 
not begin with yorY, thefile is skipped. 

D 0 not move a nondirectory that has an existing destination with the same or newer 
modification time 

Print the name of each file before moving it. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output, then exit successfully. 
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-S, --suffix backup-suffix 


-V, --version-control 
{numbered,existing,simple} 


The suffix used for making simple backup files can beset with the simple_backup_suffix 
environment variable, which can be overridden by this option. If neither of those is given, 
thedefault is", as it isin Emacs. 

The type of backups made can be set with the version_control environment variable which 
can be overridden bythisoption. IfvERSiONjxwTRoUsnotsetandthisoption isnot given, 
the default backup type is existing. T he value of the version_control environment variable 
and the argument to this option are likethe G N U Emacs version-control variable they 
also recognize synonyms that are more descriptive. 

The valid values are the following (unique abbreviations are accepted): 
t or numbered'-Alwaysmakenumbered backups 

nil or existing --M ake numbered backups of files that already have them, simple backups of 
the others. 

never or simple- Always make simple backups. 


GNU FileUtilities 


mwrite 

mwrite — Low-level write (copy) a U NIX file to MS-DOS 

SYNOPSIS 

mwrite [ -tnvmoOsSrRA ] unixfile msdosfile 

mwrite [ -tnvmoOsSrRA ] unixfile [ unixfiles... ] msdosdi rectory 

DESCRIPTION 

Thiscommand isobsoleteand only supplied for backward compatibility reasons with old scripts Usemcopy instead. 

SEE ALSO 

mcopy(l), mtools(l) 

Local 


namei 

namei- Follow a pathname until a terminal point isfound 

SYNOPSIS 

namei [-mx] pathname [ pathname ... ] 

DESCRIPTION 

namei uses its arguments as pathnames to any type of UN IX file (symlinks, files directories and so forth), namei then follows 
each pathname until a terminal point isfound (a file directory, char device, and so on). If it finds a symbolic link, the user 
shows the link, and startsfollowing it, indenting the output to show the context. 

Thisprogram is useful for finding too many levels of symbolic links problems. 

For each line output, namei outputs the following characters to identify the file types found: 
f: The pathname the user iscurrently trying to resolve 

d Directory 

1 Symbolic link (both the link and its contents are output) 

s Socket 



Parti: User Commands 

b Block device 

c Character device 

Regular file 

? An error of some kind 

Name! prints an informative message when the maximum number of symbolic links this system can have has been exceeded. 

OPTIONS 

-x Show mount point directories with a d rather than a d. 

-m Show the mode bits of each file type in the style of is(l), for example, rwxr-xr-x. 



AUTHOR 

Roger Southwick (rogers@amadeus.wr.tek.com) 

BUGS 

To be discovered 

CAVEATS 

name! will follow an infinite loop of symbolic links forever. To escape usesiGiNT (usually "c). 

SEE ALSO 

ls(l), stat(l) 

Local 


newaliases 

newaiiases— Rebuild the database for the mail aliases file 

SYNOPSIS 

newaliases 

DESCRIPTION 

newaliases rebuilds the random access database for the mail aliases file It must be run each time it is changed in order for the 
change to take effect. 

SEE ALSO 

aliases(5), sendmail(8) 

HISTORY 

The newaliases command appeared in BSD 4.0. 

BSD 4, 30 July 1991 


newgrp 

newgrp— Log in to a new group 

SYNOPSIS 


newgrp [ group ] 



nl 




DESCRIPTION 

newgrp changes the group identification of its caller, analogously to iogin(l). The same person remains logged in, and 
the current directory is unchanged, but calculations of access permissionsto files are performed with respect to the new 
group ID. 

If no group is specified, the GID ischanged to the login GID. 

FILES 

/etc/group 

/etc/passwd 


SEE ALSO 

login(l), group(5) 


Linux0.99, 9 October 1993 


nl 

ni— N umber lines of files 

SYNOPSIS 

nl [-h header-style] [-b body-style] ]-f footer-style] [-p] [-d cc] 

]-v start-number] ]-i increment] [-1 lines] ]-s line-separator] 

]-w line-no-width] [-n {ln,rn,rz}] [--header-numbering=style] 

[--body-numbering=style] [--footer-numbering=style] 

[--first-page=number] [--page-increment=number] [--no-renumber] 

[- -join-blank-lines=number] [--number-separator=string] 

[- - number-width=number] [- - number-format={ln,rn,rz}] 

[--section-delimiter=cc] [--help] [--version] [file...] 

DESCRIPTION 

This manual page documents the GN U version of m. ni copies each given file or the standard input if none are given or 
when a file named - isgiven, to thestandard output, with line numbers added to some or all of the lines, 
m considers its input to be composed of logical pages; by default, the line number is reset to i at the top of each logical page, 
m treats al I of the input files as a single document; it does not reset line numbers or logical pages between files 
A logical page consists of three sections: header, body, and footer. Any of the sections can be empty. Each can be numbered 
in a different style from the others 

T he beginnings of the sectionsof logical pages are indicated in the input file by a line containing nothing except one of the 
following delimiter strings: 

\:\:\: start of header 
\:\: start of body 
\: start of footer 

The two characters from which these strings are made can be changed with an option (see the next subsection), but the 
pattern and length of each string cannot be changed. 

The section delimiter strings are replaced by an empty line on output. Any text that comes before the first section delimiter 
string in the input file is considered to be part of a body section, so a file that does not contain any section delimiter strings is 
considered to consist of a single body section. 

OPTIONS 

-h, --header-numbering=style See --footer-numbering. 

-b, --body-numbering=style See --footer-numbering. 
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-f, --footer-numbering=style 


-p, - - no-renumber 

-v, --first-page=number 

-i, --page-increment=number 

-1, -■join-blank-lines=number 


-s, --number-separator=string 

-w, --number-width=number 
-n, --number-format=-{ln,rn,rz} 


-d, --section-delimiter=cc 


Select the numbering stylefor lines in the footer section of each logical page When a line is 
not numbered, the current line number is not incremented, but the line number separator 
character is still prepended to the line. The styles are 
a Number all lines 

t N umber only nonempty lines (default for body) 

n N umber no lines (default for header and footer) 

pregexp N umber only lines that contain a match for regexp 

D o not reset the line number at the start of a logical page. 

Set the initial line number on each logical page to number (default i). 

Increment line numbers by number (default i). 

Consider number (default i) consecutive empty lines to beonelogical linefor numbering, 
and only number the last one Where fewer than number consecutive empty lines occur, do 
not number them. An empty line is one that contains no characters, not even spaces or tabs. 
Separate the line number from the text li ne in the output with string (default is a tab 
character). 

U se number characters for line numbers (default 6). 

Select the line numbering format: 
in Left justified, no leading zeros 

™ Right justified, no leading zeros (default) 
rz Right justified, leading zeros 

Sbt the two delimiter characters that indicate the beginnings of logical page sections; if only 
one is given, the second remains:. To enter \, use \\. 

Print a usage message and exit with a nonzero status. 

Print version information on standard output, then exit. 
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nimconv— Convert object code into an N LM 

SYNOPSIS 

nlmconv[ -lb fdname ]■-input-target=bfdname] [ -Ob f d n a me | 

--output-target=l)f d na me ] [ -Theade r f i I e | - - header-f ile=h ead er file ] 

[ -V|--version ][ - - help ] infile outfile 

DESCRIPTION 

nimconv converts the relocatable object file inf lie into the N etW are Loadable M odule (N L M) outfile, optionally reading 
headerfiie for N LM header information. For instructions on writing the N LM command file language used in header files, 
seeTheNetWareTool M aker Specification M anual, available from Novell, Inc. nimconv currently workswith i 386 object files 
in COFF, ELF, ora.out format, and with SPARC object filesin ELF ora. out format, nimconv usestheGN U binary file 
descriptor library to read infile. 

OPTIONS 

-i bf dname , Consider the sourcefile'sobject format to be bfdname, rather than attempting to deduce it. 

- -input-targetS f d n a me 

-o bfdname, W rite the output file using the object format bf dname. nimconv infers the output format 

-- output-targets f dname based on the input format, for example, for an i386 input filethe output format is 

nlm32-i386. 



Reads header fi i e for N LM header information. For instructions on writing the N LM 
command fi le language used i n header fi les, see The Net 1/1/ are Tool M aker Sped ficati on 
M anual, available from N ovell, Inc. 

Show the version number of nimconv and exit. 

Show a summary of theoptionsto nimconv and exit. 


SEE ALSO 

binutiis entry in into; TheGNU BinaryUtilities, Roland FI. Pesch (June 1993). 

COPYING 

Copyright © 1993 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided the copyright notice and this permission notice are preserved on all copies 
Permission isgranted to copy and distribute modified versions of this manual under the conditionsfor verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to thisone. 
Permission isgranted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in theoriginal English. 

Cygnussupport, June 1993 


nm 

nm— List symbols from object files 

SYNOPSIS 

nm [ -aj--debug-syms][-g|■-extern-only ][-B ][-C|■-demangle ] 

[-D|--dynamic ][-sJ--print-armap][- 0 1--print-file-name] 

[-n;--numeric-sort ] [-p] --no-sort ][-r]--reverse-sort ][--size-sort ] 

[ -u]--undefined-only][--help ][--version ][-t radix]--radix=radi x ] 

[ -P]-portability ] [ -f f or mat ]--format=f or mat ][--target=bf dname ][ objfile ...] 


DESCRIPTION 

GNU nm lists the symbolsfrom object files o bj fi i e. If no object files are given asarguments, nm assumes a. out. 


OPTIONS 

The long and short forms of options, shown here as alternatives are equivalent. 


-A, -0 


Precede each symbol by the name of the input file where it wasfound, rather than 
identifying the input file once only before all of its symbols. 

D isplay debugger-only symbols; normally these are not listed. 

Thesame as --format=bsd (for compatibility with the M I PS nm). 

Decode (demangle) low-level symbol names into user-level names. Besides removing any 
initial underscore prepended by the system, this makes C++function names readable. 

D isplay the dynamic symbols rather than the normal symbols T his is only meaningful for 
dynamic objects such ascertain types of shared libraries 

Use the output format for mat , which can bebsd, sysv, or posix. The default is bsd. Only the 
first character of format is significant; it can be either uppercase or lowercase. 

D isplay only external symbols. 

Sort symbols numerically by their addresses not alphabetically by their names 
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-P, --portability 

-r, - - reverse-sort 


--targets dname 
-u, - -undefined-only 
--help 


D on't bother to sort the symbols in any order; just print them in the order encountered. 
UsethePOSIX.2 standard output format instead of the default format. Equivalent to -f 

posix. 

When listing symbolsfrom archive members, include the index, a mapping (stored in the 
archive by ar or ranim) of which modules contain definitionsfor what names. 

Reverse the sense of the sort (whether numeric or alphabetic); let the last come first. 

Sort symbols by size T he size is computed as the difference between the value of the symbol 
and the value of the symbol with the next higher value The size of the symbol is printed, 
rather than the value. 

Useradi * as the radix for printing the symbol values It must bed for decimal, o for octal, 
or x for hexadecimal. 

Specify an object code format other than your system's default format. Seeobjdump(l) for 

information on listing available formats 

Display only undefined symbols (those external to each object file). 

Show the version number of nm and exit. 

Show a summary of theoptionsto nm and exit. 


SEE ALSO 

binutiis entry in into ;TheGNU Binary Utilities, Roland H. Pesch (October 1991); ar(i), objdump(i), ramib(i). 

COPYING 

Copyright © 1991 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided the copyright notice and this permission notice are preserved on all copies 
Permission isgranted to copy and distribute modified versions of this manual under the conditionsfor verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 
Permission isgranted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in theoriginal English. 

Cygn us support, 5 N ovemberl991 


nntpget 

nntpget— G dt U senet articlesfrom a remote N N T P server 

SYNOPSIS 

nntpget [ -d dist ][-f file ][-n newsgroups ][-t timestring ][-o ][-u file ][-v ] host 

DESCRIPTION 

nntpget connects to the N N TP server at the specified host and retrieves articles from it. The articles are sent to standard 
output. 

The-o flag may be used only if the command isexecuted on the host where the innd(8) server is running. If thisflag is used, 
nntpget connects to the specified remote host to retrieve articles Any article not present in the local history database is then 
fetched from the remote site and offered to the local server. 

If the -v flag is used with the-o flag, then the M essage-ID of each article will be sent to standard output as it is processed. 
The list of article Message-1 D sis normally read from standard input. If the-f flag isused, then a newnews command is used 
to retrieve all articles newer than the modification date of the specified f i i e. The -u flag is the same except that if thetransfer 
succeeded, the file will be updated with a statistics line modifying its timestamp so that it can be used in later invocations. If 
the -t flag is used, then the specified ti mestri ng isused as the time and date parameter to the newnews command. 



If either the -t or -t flags are used, then the -n flag may be used to specify a newsgroup list and the -d flag may be used to 
specify a distribution list. The default is* for all newsgroups, and no distribution list. 


BUGS 

T runcates articles at 512 lines. 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for I nterN etl\l ews 

SEE ALSO 

innd(8) 


objcopy 

ob j copy— C opy and translate object files 

SYNOPSIS 

objcopy [ -Fbfdname |- - target=b f d n a me ] 

[ -Ibfdname] ■ -input-target=l)f d n a me ] [ -Obf d n a me | 

- -output-target=b f d n a me ] [ -Rs ectionname | 

--remove-section=sect i o n n a me ] [ -S| --strip-all ][-g| 
--strip-debug ][-xJ--discard-all ][-X] 

- - discard-locals ] [-bb y t e | - - byte=b y t e ] [ -lint er I b.tte | 
--interleaved nter I eave ] [ -v|--verbose][-V| 

--version ] [ --help ] infile [ outfile ] 


DESCRIPTION 

TheGNU objcopy utility copiesthecontentsof an object file to another, objcopy usestheGNU BFD library to read and 
write theobject files It can write the destination object filein a format different from that of the source object file. Theexact 
behavior of objcopy iscontrolled by command-lineoptions. 

objcopy creates temporary files to do its translations and deletes them afterward, objcopy uses BFD to do all its translation 
work; it knows about all theformatsBFD knows about, and thus is able to recognize most formats without being told 
explicitly. 

infiie and outfile are the source and output files, respectively. If you do not specify outfile, objcopy creates a temporary file 
and destructively renames the result with the name of the input file 


OPTIONS 

-I bfdname, 

- -input-target=b f d n a me 

- -output-target=bf dna me 



Consider the source file's object format to be bf d name, rather than attempting to deduce it. 
W rite the output file using the object format bf d n a me. 

U se bf b n a me as theobject format for both the input and the output file; that is, simply 
transfer data from source to destination with no translation. 

Remove the named section from thefile. Thisoption may be given more than once N ote 
that using this option inappropriately may make the output file unusable. 

Do not copy relocation and symbol information from the source file. 

D o not copy debuggi ng symbolsfrom the source file. 

D o not copy nonglobal symbolsfrom the source file 

Do not copy compiler-generated local symbols (These usually start with l or.). 
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-b byte, --byte=by t e 


Keep only every byte byte of the input file (header data is not affected), byte can beinthe 
range from oto the interieave-i. Thisoption is useful for creating files to program ROM & 
It istypically used with an srec output target. 

Only copy one out of every interleave bytes The one to copy is selected by the -b or 
■ -byte option. T he default is 4 . T he interleave is ignored if neither -b nor - -byte isgiven. 
Verbose output: list all object files modified. In the case of archives objcopy -v lists all 
members of the archive. 

Show the version number of objcopy and exit. 

Show a summary of theoptionsto objcopy and exit. 


SEE ALSO 

binutiis entry in info; The GNU Binary Utilities, Roland H. Pesch (June 1993). 

COPYING 

Copyright © 1993 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided the copyright notice and this permission notice are preserved on all copies 
Permission isgranted to copy and distribute modified versions of this manual under the conditionsfor verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 
Permission isgranted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in theoriginal English. 

Cygnus support, Junel993 


objdump 

ob j dump- Display information from object files 

SYNOPSIS 

objdump [ -a|--archive-headers ][-b\ b f d n a me | --target= b f d n a me ] 

[ -d|--disassemble][-D|--disassemble-all ][-fJ--file-headers ] 

[ -h]--section-headers | --headers ][-11- - info ][-j\ section 
| --section= section ][-1|--line-numbers ][-m\ machine ] -- 
-architecture= machi ne ][-r|--reloc ][-R|--dynamic-reloc ] 

[ -s|--full-contents ][- - stabs ][-t|- - syms ] [-T| --dynamic- 
syms] [-x j --all-headers ][--version ][- - help ] objfile ... 

DESCRIPTION 

objdump displays information about oneor more object files. The options control what particular information to display. This 
information is mostly useful to programmers who are working on the compilation tools, as opposed to programmers who 
just want their program to compile and work. 

objfile... are the object files to be examined. When you specify archives, objdump shows information on each of the member 
object files. 

OPTIONS 

Where long and short forms of an option are shown together, they are equivalent. At least one option besides -i (--une- 
numbers) must be given. 

-a, --archive-headers If any filesfrom objfile are archives, display the archive header information (in a format 

similar to is -l). Besides the information you could list with ar tv,objdump -a shows the 
object file format of each archive member. 



-d, --disassemble 

-D, --disassemble-all 

-f, --file-headers 
-h, --section-headers, 
--headers 




1, --line-numbers 


--architectures chi ne 


-R, - -dynamic-reloc 
-s, --full-contents 


-T, --dynamic-syms 


-x, --all-headers 


Specify the object-code format for the object files to be bf d na me . T his may not be necessary; 
obj dump can automatically recognize many formats. For example, objdump -b oasys -m vax - 
h fu.o displays summary information from the section headers (-h) of fu.o, which is 
explicitly identified (-m) asa Vax object file in theformat produced by Oasys compilers You 
can list theformats available with the-i option. 

D isplay the assembler mnemonicsfor the machine instructions from obj f i e . T hisoption 
only disassembles those sections that are expected to contain instructions. 

Like -d, but disassemble the contents of all sections not just those expected to contain 
instructions. 

Display summary information from the overall header of each file in obj f i i e. 

Display summary information from the section headers of the object file 

Printasummaryoftheoptionsto obj dump and exit. 

Display a list showing all architectures and object formatsavailablefor specification with -b 
or-m. 

Display information only for section name. 

Label thedisplay (using debugging information) with the filename and source line numbers 
corresponding to theobject code shown. 0 nly useful with -d or -d. 

Specify theobject filesobj fi i e are for architecture mac hi ne. You can list available architec¬ 
tures using the-i option. 

Print the relocation entries of thefile. If used with -d or -d, the relocations are printed 
interspersed with the disassembly. 

Print the dynamic relocation entries of thefile. This is only meaningful for dynamic objects, 
such ascertain types of shared libraries 
D isplay the full contents of any sections requested. 

Display the contents of the .stab, .stab, index, and .stab.exci sections from an ELF file. 
This is only useful on systems (such as Solaris 2.0) in which .stab debugging symbol-table 
entries are carried in an ELF section. In most other file formats debugging symbol-table 
entries are interleaved with linkage symbols and are visible in the --syms output. 

Symbol table Print the symbol table entries of the file This is similar to the information 
provided by the nm program. 

Dynamic symbol table. Print the dynamic symbol table entries of thefile This isonly 
meaningful for dynamic objects, such ascertain types of shared libraries. This issimilar to 
the information provided by the nm program when given the -d (--dynamic) option. 

Print the version number of obj bump and exit. 

Display all available header information, including the symbol table and relocation entries 
U sing-xisequivalent to specifying all of -a -f -h -r -t. 


SEE ALSO 

binutiis entry in into; TheGNU BinaryUtilities, Roland FI. Pesch (October 1991); nm(i). 

COPYING 

Copyright © 1991 Free Software Foundation, Inc. Permission isgranted to make and distribute verbatim copies of this 
manual provided the copyright notice and this permission notice are preserved on all copies 
Permission isgranted to copy and distribute modified versions of this manual under the conditionsfor verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to thisone. 
Permission isgranted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in theoriginal English. 


Cygnussupport, 5 N ovemberl991 
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oclock 

ociock—Round X clock 

SYNOPSIS 

oclock [-option ... ] 

DESCRIPTION 

ociock simply displays the current time on an analog display. 

OPTIONS 

-fg col or 
-bg col or 

-minute color 

-backing {whenMapped 
Always NotUseful} 

-geometry geomet ry 
-display display 


-noshape 
-transparent 

COLORS 

If you would like your clock to be viewable in color, include the following in the#itdef color section you read with xrdb: 

‘customization: -color 

This will cause ociock to pick up the colors in the app-defaults color customization file: <xRoot>/iib/xii/app-defauits/ 

ciock-coior. The default colorsare 

Clock*Background Gray 

Clock*BorderColor Light blue 

Clock*hour YdlOW 

Clock*] ewel Yellow 

Clock*minute YdlOW 

SEE ALSO 

x(l), X Toolkit documentation 

AUTHOR 

Keith Packard, M IT X Consortium 


C hoose a different color for both hands and the jewel on the clock 
C hoose a different color for the background. 

C hoose a different color for the jewel on the clock. 

C hoose a different color for the minute hand of the clock. 

C hoose a different color for the hour hand of the clock. 

Select an appropriate level of backing store. 

Define the initial window geometry; seex(l). 

Specify the display to use; seex(l). 

C hoose a different color for the window border. 

C hoose a different width for the wi ndow border. As the C lock widget changes its border around 
quite a bit, this is most usefully set to zero. 

Cause thedock to use the Shape extension to create an oval window. Thisisthe default unless the 
shapewindow resource is set to false. 

C ause the clock to not reshape itself and ancestors to exactly fit the outline of the clock. 

C ause the clock to consist only of the jewel, the hands, and the border. 


X Verson 11 Release6 
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od 

od— D ump files in octal and other formats 

SYNOPSIS 

od [-abcdfhiloxv] [-s[bytes]] [-w[bytes]] [-A radix] [-j bytes] [-N bytes] 
[-t type] [--skip-bytes=bytes] [■-address-radix=radix] [--read-bytes=bytes] 
[--format=type] [--output-duplicates] [--strings[=bytes]] [--width[=bytes]] 
[--traditional] [--help] [--version] [file...] 


DESCRIPTION 

This manual page documents the GN U version of od. od writes to the standard output the contents of the given files, or of 
thestandard input if the name - isgiven. Each line of the output consists of the offset in the input file in the leftmost 
column of each line, followed by one or more columns of data from thefile, in a format controlled bytheoptions By 
default, od pri nts the file offsets in octal and the file data as two-byte octal numbers 


OPTIONS 

-A, --address-radix=radi* 


-j, - -skip-bytes=byt es 


-N, - -read-bytes=byt es 
-t, --format=type 


Select the base in which file offsets are printed, r a d i * can be one of the following: 
d Decimal 

o Octal 

x Hexadecimal 

n None (do not print offsets) 

The default is octal. 

Skip bytes input bytes beforeformatting and writing. If bytes begins with ex or ex, it is 
interpreted in hexadecimal; otherwise, if it begins with e, in octal; otherwise, in decimal. 
Appending b multiplies it by 512, k by 1024, and m by 1048576. 

Only output up to bytes bytes of each input file. Any prefixes and suffixes on bytes are 
interpreted as for the-j option. 

Select the format in which to output the file data, type isa string of one or more of the 
following type indicator characters If you include more than onetype indicator character in 
a singlet ype string or use this option more than once, od writes one copy of each output 
line using each of the data types that you specified, in the order that you specified, 
a N amed character 

c ASC11 character or backslash escape 

d Signed decimal 

f Floatingpoint 

o Octal 

u Unsigned decimal 

x H exadecimal 

Except for types a and c, you can specify the number of bytes to use in interpreting each 
number in thegiven data type by following the type indicator character with adecimal 
integer. Alternately, you can specify the size of one of the C compiler's built-in data types by 
following the type indicator character with one of the following characters For integers (d, 

o, u, x): 

c char 

s short 

i int 

l long 
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-v, --output-duplicates 


-s, - -strings[=byt e s ] 


-w, --width[=byt es ] 

--help 


For floating point (t): 
f float 

d double 

l long double 

0 utput consecutive lines that are identical. By default, when two or more consecutive 
output lines would be equal, od outputs only the first line, and putsjust an asterisk on the 
following line to indicate that identical lines have been elided. 

I nstead of the normal output, output only string constants in the input, which are a run of 
at least bytes ASC11 graphic (or formatting) characters, terminated by a nul. If bytes is 
omitted, it defaults to 3. 

T he number of input bytes to format per output line. 11 must be a multiple of the least 
common multi pie of the sizes associated with the specified output types. If bytes is omitted, 
it defaults to 32. Ifthis option is not given, it defaults to 16. 

Print a usage message and exit with a nonzero status 
Print version information on standard output, then exit. 


The next several options map the old, pre-PO SIX format specification options to the corresponding POSIX format specs. 
GNU od accepts any combination of old- and new-style options. Format specification options accumulate. 




0 utput as named characters Equivalent to -t a. 

0 utput as octal bytes Equivalent to -t oc. 

0 utput as ASC 11 characters or backslash escapes. Equivalent to -t 0. 

0 utput as unsigned decimal shorts Equivalent to -t u2. 

Output as floats Equivalent to -t fF. 

Output as hexadecimal shorts. Equivalent to -t x2. 

Output as decimal shorts. Equivalent to -t d2. 

Output as decimal longs Equivalent to -t d 4 . 

0 utput as octal shorts. Equivalent to -t 02. 

Output as hexadecimal shorts. Equivalent to -t x2. 

Recognize the pre-PO SIX nonoption arguments that some older versions of od accepted. 
The following syntax: 

od --traditional [file] [ [+]offset [.][b] [[+] Iabel [. ] [b] ]] 

can be used to specify at most one file and optional arguments specifying an offset and a 
pseudo-start address label . By default, off set is interpreted as an octal number specifying 
how many input bytes to skip before formatting and writing. The optional trailing decimal 
point forcesthe interpretation of offset asa decimal number. If no decimal isspecified and 
the offset begins with ox or ex, it is interpreted as a hexadecimal number. If there isa trailing 
b, the number of bytes skipped will be of f set multiplied by 512. The 1 abel argument is 
interpreted just like off set , but it specifies an initial pseudo-address. The pseudo addresses 
are displayed in parentheses following any normal address. 


GNU Text Utilities 


passwd 

passwd— C hange password 

SYNOPSIS 


passwd [ name 





paste 


FI 


DESCRIPTION 

passwd changes thespecified user's password. Only the superuser is allowed to change other users' passwords If the user is 
not root, then the old password is prompted for and verified. 

A new password is prompted for twice to avoid typing mistakes Unless the user is the superuser, the new password must 
have more than six characters and must have either both uppercase and lowercase letters or nonletters Some passwords that 
are similar to the user's name are not allowed. 

FILES 

/etc/passwd 

/etc/shells 

SEE ALSO 

chsh(l), chfn(l) 

BUGS 

A password consisting of all digits is allowed. 

N o warnings are printed if the superuser choosesa poor password. 

The-f and-s options are not supported. 

AUTHOR 

Peter 0 rbaek (poe@daimi.aau.dk) 

Linux 1.0, 22]unel994 


paste 

paste- Mergelines of files 

SYNOPSIS 

paste [-s] [-d delim-list] [--serial] [--delimiters=delim-list] [--help] 
[--version] [file...] 


DESCRIPTION 

This manual page documents the GN U version of paste, paste prints lines consisting of sequentially corresponding lines of 
each given file, separated by tabs, terminated by a newline. If no files are given, the standard input is used. A filename of - 
means standard input. 


OPTIONS 

-s, --serial 

-d, --delimiters delim-list 


--version 


Paste the lines of onefile at a time rather than one line from each file 
Consecutively use the characters in deiim-iist instead of tab to separate merged lines 
When deiim-iist isexhausted, start again at its beginning. 

Print a usage message and exit with a nonzero status. 

Print version information on standard output, then exit. 


GNU Text Utilities 
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pbmclean 

pbmciean— Flip isolated pixels in portable bitmap 

SYNOPSIS 

pbmclean [-connect] [pbmfile] 

DESCRIPTION 

pbmciean readsa portable bitmap as input and outputsa portable bitmap with every pixel that hasless than connect identical 
neighborsinverted. pbmciean can be used to clean up "snow" on bitmap images. 

SEE ALSO 

pbm(5) 

AUTHOR 

Copyright © 1990 by Angus Duggan. Copyright © 1989 byjef Poskanzer. 

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is 
hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this 
permission notice appear in supporting documentation. This software is provided "as is" without express or implied 
warranty. 


pbmfilters 

pbmfliters— List of all programs in the PBM Plus package 


DESCRIPTION 

anytopnm Attempt to convert an unknown type of image file to a portable anymap 

asciitopgm Convert ASCI I graphics into a portable graymap 

atktopbm Convert Andrew Toolkit raster object to a portable bitmap 

bioradtopgm Convert a Biorad confocal file into a portable graymap 

bmptoppm Convert a BM P file into a portable pixmap 

brushtopbm Convert a doodle brush file into a portable bitmap 

cmuwmtopbm Convert a C M U window manager bitmap into a portable bitmap 

fitstopnm Convert a FITS file into a portable anymap 

fstopgm Convert a Usenix FaceSaver file into a portable graymap 

g3topbm C onvert a G roup 3 fax file into a portable bitmap 

gemtopbm ConvertaGEM IMG file into a portable bitmap 

giftopnm Convert aG IF file into a portable anymap 

gouidtoppm Convert Gould scanner file into a portable pixmap 

hipstopgm Convert a H I PS file into a portable graymap 

hpcdtoppm Convert a Photo-CD file into a portable pixmap 

icontopbm Convert a Sun icon into a portable bitmap 

iibnrtoppm Convert an ILBM file into a portable pixmap 

imgtoppm Convertan IMG-whatnotfileintoaportablepixmap 

lispmtopgm Convert a Lisp machine bitmap file into PG M format 

macptopbm Convert a M acPaint file into a portable bitmap 

mgrtopbm Convert an M G R bitmap into a portable bitmap 

mtvtoppm Convert output from the M TV or PRT ray tracers into a portable pixmap 
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pbmciean Flip isolated pixels in portable bitmap 

pbmiife Apply Conway's Rulesof Life to a portable bitmap 

pbmmake C reate a blank bitmap of a specified size 

pbramask C reate a mask bitmap from a regular bitmap 

pbmpscaie Enlarge a portable bitmap with edge smoothing 
pbmreduce Read a portable bitmap and reduce it N times 
pbmtext Render text into a bitmap 

pbmtoiox Convert a portable bitmap into Gemini 10X printer graphics 

pbmt 04425 DisplayPBM images on an AT&T 4425terminal 

pbmtoascii Convert a portable bitmap into ASC 11 graphics 

pbmtoatk Convert a portable bitmap to Andrew Toolkit raster object 

pbmtobg Convert a portable bitmap into BitG raph graphics 

pbmtocmuwm Convert a portable bitmap into a C M U window manager bitmap 

pbmtoepsi Convert a portable bitmap into an encapsulated PostScript 

pbmtoepson Convert a portable bitmap into Epson printer graphics 

pbmtog3 Convert a portable bitmap into a G roup 3 fax file 

pbmtogem Convert a portable bitmap into a G EM IMG file 

pbmtogo Convert a portable bitmap into compressed GraphOn graphics 

pbmtoicon Convert a portable bitmap into a Sun icon 

pbmtoi] Convert a portable bitmap into H P LaserJet format 

pbmtoin03 Convert portable bitmap to D EC LN 03+Sixel output 

pbmtoips Convert portable bitmap to PostScript 

pbmtomacp Convert a portable bitmap into a M acPaintfile 

pbirrtomgr Convert a portable bitmap into an M G R bitmap 

pbmtopgm C onvert a portable bitmap to portable graymap by averaging areas 

pbmtopi3 Convert a portable bitmap into an Atari D egas.pi3 file 

pbmtopk Convert a portable bitmap into a packed (PK) format font 

pbmtopiot Convert a portable bitmap into all NIX piot(5) file 

pbmtoptx Convert a portable bitmap into Printronix printer graphics 

pbmtoxi0bm Convert a portable bitmap into an X10 bitmap 

pbmtoxbm Convert a portable bitmap into an Xll bitmap 

pbmtozinc Convert a portable bitmap into a Zinc bitmap 

pbmupc Create a Universal Product Code bitmap 

pcxtoppm Convert a PCX file into a portable pixmap 

pgmbentiey Bentleyize a portable graymap 

pgmcrater C reate cratered terrain by fractal forgery 

pgmedge Edge-detect a portable graymap 

pgmenhance Edge-enhance a portable graymap 

pgmhist Print a histogram of the values i n a portable graymap 

pgmkernei Generate a convolution kernel 

pgmnoise C reate a graymap made up of white noise 

pgmnorm N ormalizethecontrast in a portable graymap 

pgmoii T urn a portable graymap into an oil painting 

pgmramp G enerate a grayscale ramp 

pgmtexture C alcul ate textural featureson a portable graymap 

pgmtofs Convert a portable graymap to U senix FaceSaver format 
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Convert a portablegraymap into Lisp machineformat 
C onvert a portable graymap into a portable bitmap 
Colorize a portable graymap into a portable pixmap 
Convert a portable bitmap into a Bennet Yee "face:' file 
Convert an Atari D egas PI 1 into a portable pixmap 
Convert an Atari Degas PI3 file into a portable bitmap 
Convert a M acintosh PICT file into a portable pixmap 
Convert an HP PaintJet file into a portable pixmap 
Convert packed (PK) formatfont into portablebitmap(s) 
Antialias a portable anymap 
Perform arithmetic on two portable anymaps 
C oncatenate portable anymaps 
C omposite two portable anymap files together 
General mxn convolution on a portable anymap 
C rop a portable anymap 
C ut a rectangle out of a portable anymap 
Change the maxvai in a portable anymap 
Read a portable anymap and enlarge it N times 
D escri be a portable anymap 

Perform one or more flip operationson a portable anymap 

Perform gamma correction on a portable anymap 

Draw a histogram for a PGM or PPM file 

Build a visual index of a bunch of anymaps 

I n vert a portable anymap 

Add a border to a portable anymap 

Nonlinear filters smooth, alpha trim mean, optimal 

Force a portable anymap into plain format 

Add borders to portable anymap 

Paste a rectangle into a portable anymap 

Rotate a portable anymap by some angle 

Scale a portable anymap 

Shear a portable anymap by some angle 

Smooth out an image 

Replicatea portable anymap into a specified size 

C on vert a portable anymap to D DIF format 

C onvert a portable anymap into F IT S format 

Convert portable anymap to PostScript 

Convert a portable pixmap into a Sun raster file 

Convert a portable anymap to an SGI image file 

Convert a portable anymap into a Solitaire format 

Convert a portable anymap into a TIFF file 

Convert a portable anymap into an Xll window dump 

Convert two portable pixmap into a red/blue 3D glasses pixmap 

Change an images Saturation and Value from an HSV map 

C hange all pixels of one color to another in a portable pixmap 

Dima portable pixmap down to total blackness 



pbmfilters 


ppmflash 



ppmntsc 

ppmpat 

ppmquant 

ppmquantall 

ppmqvga 

ppmrelief 

ppmshift 

ppmspread 

ppmtoacad 

ppmtobmp 

ppmtogif 

ppmtoicr 

ppmtoilbm 

ppmtomap 

ppmtomitsu 

ppmtopcx 

ppmtopgm 

ppmtopil 

ppmtopict 

ppmtop] 

ppmtopj xl 

ppmtopuzz 

ppmtorgb3 

ppmtosixel 

ppmtotga 

ppmtouil 

ppmtoxpm 

ppmtoyuv 

ppmtoyuvsplit 

psidtopgm 

pstopnm 

qrttoppm 

rasttopnm 

rawtopgm 

rawtoppm 

ngb3toppm 

sgitopnm 

sirtopnm 


Simplistic grayscale assignment for machine generated, color images 

0 rdered dither for color images 

Brighten a picture up to complete white-out 

Fractal forgeries of clouds, planets, and starry skies 

Print a histogram of a portable pixmap 

C reate a pixmap of a specified size and color 

Blend together two portable pixmaps 

N ormalizethecontrast in a portable pixmap 

M ake a portable pixmap look like it was taken from an American TV show 
M ake a pretty pixmap 

Quantize the colors in a portable pixmap down to a specified number 
Run ppmquant on a bunch of files all at once so they share a common colormap 
8-plane quantization 

Run a Laplacian relief filter on a portable pixmap 

Shift lines of a portable pixmap left or right by a random amount 

D isplace a portable pixmap's pixels by a random amount 

Convert portable pixmap to AutoCAD database or slide 

Convert a portable pixmap into a BM P file 

Convert a portable pixmap into a GIF file 

C onvert a portable pixmap into N C SA IC R format 

Convert a portable pixmap into an ILBM file 

Extract all colors from a portable pixmap 

Convert a portable pixmap to a M itsubishi S340-10 file 

Convert a portable pixmap into a PCX file 

C on vert a portable pixmap i nto a portable graymap 

Convert a portable pixmap into an Atari D egasPI 1 file 

Convert a portable pixmap into a M acintosh PICT file 

Convert a portable pixmap to an FI P PaintJet file 

Convert a portable pixmap into an H P PaintJetXL PC L file 

Convert a portable pixmap into an Xll "puzzle" file 

Separate a portable pixmap into three portable graymaps 

Convert a portable pixmap into D EC sixel format 

Convert portable pixmap into aTrueVision Targafile 

Convert a portable pixmap into a M otif UIL icon file 

Convert a portable pixmap into an Xll pixmap 

Convert a portable pixmap into an Abekas YU V file 

Convert a portable pixmap into three subsampled raw YU V files 

C onvert PostScript "image" data into a portable graymap 

Convert a PostScript file into a portableanymap 

Convert output from the QRT ray tracer into a portable pixmap 

Convert a Sun raster file into a portable anymap 

C onvert raw grayscale bytes into a portable graymap 

Convert raw RG B bytes into a portable pixmap 

Combine three portable graymaps into one portable pixmap 

Convert an SGI image file into a portable anymap 

Convert a Solitaire file into a portable anymap 
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Convert an AutoCAD slide file into a portable pixmap 

Convert an Atari compressed Spectrum file into a portable pixmap 

Convert SPOT satellite images to Portable Graymap format 

Convert an Atari uncompressed Spectrum file into a portable pixmap 

Convert TrueVision Targa file into a portable pixmap 

C on vert a TIF F file i nto a portable anymap 

Convert an Xll or X10 bitmap into a portable bitmap 

Convert anXIM file into a portable pixmap 

Convert an Xll pixmap into a portable pixmap 

Convert an XV thumbnail picture to PPM 

Convert an Xll or X10 window dump file into a portable anymap 

Convert a Bennet Yee "face: 1 file into a portable bitmap 

Convert a Y-, U- and V-fileinto a portable pixmap 

Convert Abekas YU V bytes into a portable pixmap 

C onvert a Zeiss confocal file into a portable anymap 


anytopnm(l), asciitopgm(l), atktopbm(l), bioradtopgm(l), bmptoppm(l), brushtopbm(l), cmuwmtopbin(l), fitstopnm(l), fstopgm(l), 
g3topbm(l), gemtopbm(l), giftopnm(l), gouldtoppm(l), hipstopgm(l), hpcdtoppm(l), icontopbm(l), ilbmtoppm(l), imgtoppm(l), 
lispmtopgm(l), macptopbm(l), mgrtopbm(l), mtvtoppm(l), pbmclean(l), pbmlife(l), pbmmake(l), pbmmask(l), pbmpscale(l), 
pbmreduce(l), pbmtext(l), pbmto10x(l), pbmto4425(l), pbmtoascii(l), pbmtoatk(l), pbmtobbnbg(l), pbmtocmuwm(l), pbmtoepsi(l), 
pbmtoepson(l), pbmtog3(l), pbmtogem(l), pbmtogo(l), pbmtoicon(l), pbmtolj(l), pbmtoln03(l), pbmtolps(l), pbmtomacp(l), 
pbmtomgr(l), pbmtopgm(l), pbmtopi3(l), pbmtopk(l), pbmtoplot(l), pbmtoptx(l), pbmtox10bm(l), pbmtoxbm(l), pbmtoybm(l), 
pbmtozinc(l), pbmupc(l), pcxtoppm(l), pgmbentley(l), pgmcnater(l), pgmedge(l), pgmenhance(l), pgmhist(l), pgmkernel(l), 
pgmnoise(l), pgmnorm(l), pgmoil(l), pgmramp(l), pgmtexture(l), pgmtofs(l), pgmtolispm(l), pgmtopbm(l), pgmtoppm(l), 
piltoppm(l), pi3topbm(l), picttoppm(l), pjtoppm(l), pktopbm(l), pnmalias(l), pnmarith(l), pnmcat(l), pnmcomp(l), pnmconvol(l), 
pnmcrop(l), pnmcut(l), pnmdepth(l), pnmenlarge(l), pnmfile(l), pnmflip(l), pnmgamma(l), pnmhistmap(l), pnmindex(l), 
pnminvert(l), pnmmargin(l), pnmnlfilt(l), pnmnoraw(l), pnmpad(l), pnmpaste(l), pnmrotate(l), pnmscale(l), pnmshear(l), 
pnmsmooth(l), pnmtile(l), pnmtoddif(l), pnmtofits(l), pnmtops(l), pnmtorast(l), pnmtosgi(l), pnmtosir(l), pnmtotiff(1), 
pnmtoxwd(l), ppm3d(l), ppmbrighten(l), ppmchange(l), ppmdim(l), ppmdist(l), ppmdither(l), ppmflash(l), ppmforge(l), 
ppmhist(l), ppmmake(l), ppmmix(l), ppmnorm(l), ppmntsc(l), ppmpat(l), ppmquant(l), ppmquantall(l), ppmqvga(l), ppmrelief(1), 
ppmshift(l), ppmspread(l), ppmtoacad(l), ppmtobmp(l), ppmtogif(l), ppmtoicr(l), ppmtoilbm(l), ppmtomap(l), ppmtomitsu(l), 
ppmtopcx(l), ppmtopgm(l), ppmtopil(l), ppmtopict(l), ppmtopj(1), ppmtop]xl(l), ppmtopuzz(l), ppmtorgb3(l), ppmtosixel(l), 
ppmtotga(l), ppmtouil(l), ppmtoxpm(l), ppmtoyuv(l), ppmtoyuvsplit(l), psidtopgm(l), pstopnm(l), qrttoppm(l), nasttopnm(l), 
nawtopgm(l), rawtoppm(l), rgb3toppm(l), sgitopnm(l), sirtopnm(l), sldtoppm(l), spctoppm(l), spottopgm(l), sputoppm(1), 
tgatoppm(l), tifftopnm(l), xbmtopbm(l), ximtoppm(l), xpmtoppm(l), xvminitoppm(l), xwdtopnm(l), nybmtopbm(l), 
yuvsplittoppm(l), yuvtoppm(l), zeisstopnm(l) 


AUTHORS 

M any. Seethe individual manual pages. 


pbmlife 

pbmiife— Apply Conway's Rules of Life to a portable bitmap 


pbmlife [pbmf i I e 



pbmmask 


353 

DESCRIPTION 

pbmiife reads a portable bitmap as input, applies the Rules of Life to it for one generation, and produces a portable bitmap as 
output. 

A white pixel in the image is interpreted as a live beastie, and a black pixel as an empty space 

SEE ALSO 

pbm(5) 

AUTHOR 

Copyright © 1988,1991 byjef Poskanzer 

21 February 1991 


pbmmake 

pbmmake— C reate a blank bitmap of a specified size 

SYNOPSIS 

pbnimake [-white \-black | -gray ] width height 

DESCRIPTION 

pbnimake produces a portable bitmap of the specified width and height. The color defaults to white. 

OPTIONS 

In addition to the usual -white and -black, this program implements -gray. Thisgivesa simple 50 percent gray pattern with 
l'sand 0's alternating. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pbm(5), ppmmake(l) 

AUTHOR 

Copyright © 1989 byjef Poskanzer 

22 February 1989 


pbmmask 

pbmmask- C reate a mask bitmap from a regular bitmap 

SYNOPSIS 

pbmmask [-expand] [pbmf i I e] 

DESCRIPTION 

pbmmask reads a portable bitmap as input and creates a corresponding mask bitmap and writes it out. 

The color to be interpreted as background isdetermined automatically. Regardless of which color is background, the mask 
will be white where the background iswhiteand black where thefigure is black. 
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T his lets you do a masked paste like this, for objects with a black background: 

pbmmask obj > objmask 

pnmpaste < dest -and objmask <x><y>!pnmpaste -or obj <x><y> 

For objects with a white background, you can either invert them or add a step: 

pbnimask obj > objmask 

pnminvert objmask | pnmpaste -and obj 0 0 > blackback 

pnmpaste < dest -and objmask <x><y>|pnmpaste -or blackback <x><y> 

N ote that this three-step version works for objects with black backgrounds, too, if you don't care about the wasted time 
You can also use masks with graymapsand pixmaps, using the pnmarith tool. For instance 

ppmtopgm obj.ppm | pgmtopbm -threshold | pbmmask > objmask.pbm 
pnmarith -multiply dest.ppm objmask.pbm > tl.ppm 
pnminvert objmask.pbm ] pnmarith -multiply obj.ppm - > t2.ppm 
pnmarith -add tl.ppm t2.ppm 

An interesting variation on thisisto pipe the mask through the pnmsmooth script before using it. This makes theboundary 
between thetwo images less sharp. 

OPTIONS 

-expand Expands the mask by one pixel out from the image T his is useful if you want a little white border around your 

image (A better solution might beta turn thepbmiife tool into a general cellular automaton tool...) 

SEE ALSO 

pnmpaste(l), pnminvert(l), pbm(5), pnmarith(l), pnmsmooth(l) 

AUTHOR 

Copyright © 1988 byJef Poskanzer 

8 August 1989 


pbmpscale 

pbmpscaie— Enlarge a portable bitmap with edge smoothing 

SYNOPSIS 

pbmpscale N [ pbmf i I e ] 

DESCRIPTION 

pbmpscale reads a portable bitmap as input and outputs a portable bitmap enlarged N times. Enlargement is done by pixel 
replication, with some additional smoothing of corners and edges 

SEE ALSO 

pnmenlarge(l), ppmscale(l), pbm(5) 

AUTHOR 

Copyright© 1990 by Angus Duggan. Copyright© 1989 by Jef Poskanzer. 

NOTES 

pbmpscale works best for enlargements of 2. Enlargements greater than 2 should be done by as many enlargements of 2 as 
possible followed by an enlargement by the remaining factor. 
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pbmreduce 

pbmreduce— Read a portable bitmap and reduce it N times 

SYNOPSIS 

pbmreduce [-floyd]-fs|-threshold ][-value v a I ] N [pbmfile] 

DESCRIPTION 

pbmreduce reads a portable bitmap as input, reduces it by a factor of n, and produces a portable bitmap as output, 
pbmreduce duplicates a lot Of the functionality Of pgmtopbm; you could do something like pnmscale ] pgmtopbm, but pbmreduce 
is a lot faster. 

pbmreduce can be used to "re-halftone" an i mage. Say you have a scanner that only produces black and white, not grayscale, 
and it does a terrible job of halftoning (most black-and-white scanners fit this description). 0 ne way to fix the halftoning is 
to scan at the highest possible resolution, say 300dpi, and then reduce by a factor of three or so using pbmreduce.You can even 
correct the brightness of an image, by using the -value flag. 

OPTIONS 

By default, the halftoning after the reduction is done via boustrophedonic Floyd-Steinberg error diffusion; however, the - 
threshold flag can be used to specify simple thresholding. Thisgives better results when reducing line drawings 
The - value flag alters the thresholding value for all quantizations It should be a real number between 0 and 1. Above 0.5 
meansdarker images; below 0.5 means lighter. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pnmenlarge(l), pnmscale(l), pgmtopbm(l), pbm(5) 

AUTHOR 

Copyright © 1988 byJef Poskanzer 

2 August 1989 


pbmtext 

pbmtext— Render text into a bitmap 

SYNOPSIS 

pbmtext [-font f ont f i I e ][-bulltln f ont name ] [t ext ] 

DESCRIPTION 

pbmtext takes the specified text, either a single line from the command line or multiple lines from standard input, and renders 
it into a bitmap. 

OPTIONS 

By default, pbmtext usesa built-in font called bdf (about a 10-point Times Roman font). You can use a fixed-width font by 
specifying -butitin fixed. 

You can also specify your own font with the -font flag. The f ont f i i e is either a BDF file from theX Window System ora 
PBM file 
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If the f ont f i i e isaPBM file, it iscreated in a very specific way. In your window system of choice display the following text 
in the desired (fixed-width) font: 

M ",/• [ 1 jpqy; M 
/ !■#$%&■<)*+ / 

< ,-./01234567 < 

> 89: ;<=>?@ABC > 

G> DEFGHIJKLMNO G> 

PQRSTUVWXYZ [ 

{ \]" 'abcdefg { 

} hijklmnopqrs } 

M ",/• [ 1 jpqy| M 

Do ascreen grab or window dump of that text, using for instance xwd, xgrabsc, or screen-dump. Convert the result into a 
PBM file If necessary, usepnmcut to remove everything except the text. Finally, run it through pnmcrop to make sure the 
edges are right up against thetext. pbmtext can figure out the sizes and spacingsfrom that. 

SEE ALSO 

pbm(5), pnmcut(l), pnmcrop(l) 

AUTHOR 

Copyright© 1993 byjef Poskanzer and George Phillips 

26 October 1993 


pbmtolOx 

pbmtoiox—Convert a portable bitmap into Gemini 10X printer graphics 

SYNOPSIS 

pbmtolOx [ - h] [pbmf i I e ] 

DESCRIPTION 

pbmtoiox readsa portable bitmap as input and produces a file of Gemini 10X printer graphics asoutput. The 10X'sprinter 
codes are alleged to be similar to theEpson codes. 

Note that there is no loxtopbm tool; thistransformation isone-way. 

OPTIONS 

The resolution is normally 60H by 72V. If the -h flag is specified, resolution is 120H by 144V. You may find it useful to 
rotate landscape images before printing. 

SEE ALSO 

pbm(5) 

AUTHOR 

Copyright © 1990 by Ken Yapl 


January 1990 
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pbmto4425 

pbmto4425—Display PBM images on an AT&T 4425 terminal 

SYNOPSIS 

pbmto4425 [pbmf i Ie] 

DESCRIPTION 

Pbmto4425 displaysPBM format imageson an AT&T 4425 ASCII terminal usingthatterminal'smosaicgraphicscharacter 
set. T he program should also work with other VT 100-like terminals with mosaic graphics character sets such as the C. Itoh 
C IT-101, but it has not yet been tested on terminals other than the 4425. 

Pbmto4425 puts the terminal into 132-column mode to achieve the maximum resolution of the terminal. In this mode the 
terminal has a resolution of 264 columns by 69 rows The pixels have an aspect ratio of 1:2.6; therefore an image should be 
processed before being displayed in a manner such as this: 

% pnmscale -xscale 2.6 pnmfile \ 

] pnmscale -xysize 264 69 \ 

I ppmtopgm \ 

| pgmtopbm \ 

| pbmto4425 

AUTHOR 

Copyright © 1993 by Robert Perlberg 

pbmtoascii 

pbmtoascii— C onvert a portable bitmap into ASC11 graphics 

SYNOPSIS 

pbmtoascii [-1x2j-2x4] [pbmf i I e ] 

DESCRIPTION 

pbmtoascii readsa portable bitmap as input and produces a somewhat crude ASC II graphic asoutput. 

N otethat there is no asciitopbm tool; this transformation is oneway. 

OPTIONS 

The-ix2 and -2x4 flags providetwo alternate waysfor the bits to get mapped to characters. With 1x2, the default, each 
character represents a group of 1 bit across by 2 bits down. W ith -2x4, each character represents 2 bits across by 4 bits down. 
With the 1x2 mode you can see the individual bits, so it's useful for previewing small bitmapson a nongraphics terminal. 
The 2x4 mode Idtsyou display larger bitmapson a standard 80-column display, but it obscures bit-level details 2x4 mode is 
also good for displaying graymaps. pnmscale -width 158 I pgmnorm \ pgmtopbm -thresh should give good results. 

SEE ALSO 

pbm(5) 

AUTHOR 

Copyright © 1988,1992 byjef Poskanzer 


20 March 1992 
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pbmtoatk 

pbmtoatk— Convert portable bitmap to Andrew Toolkit raster object 

SYNOPSIS 

pbmtoatk [pbmf i I e] 

DESCRIPTION 

pbmtoatk reads a portable bitmap as input and produces an Andrew T oolkit raster object asoutput. 

SEE ALSO 

atktopbm(l), pbm(5) 

AUTHOR 

Copyright © 1991 by Bill Janssen 

26 September 1991 


pbmtobg 

pbmtobg- Convert a portable bitmap into BitGraph graphics 

SYNOPSIS 

pbmtobg [rast erop][* y]< pbmf i I e 

DESCRIPTION 

pbmtobg readsa portable bitmap as input and produces BBN BitGraph terminal display pixel data (D PD) sequence asoutput. 
Therasterop can be specified on the command line. If this is omitted, 3 (replace) will be used. A position in (x,y) coordi¬ 
nates can also be specified. If both are given, the rasterop comes first. The portable bitmap is always taken from the standard 
input. 

Notethatthereisno bgtopbmtool. 

SEE ALSO 

pbm(5) 

AUTHOR 

Copyright © 1989 by M ike Parker 

16 May 1989 


pbmtocmuwm 

pbmtocmuwm- Convert a portable bitmap into a C M U window manager bitmap 

SYNOPSIS 

pbmtocmuwm [pbmfi I e ] 

DESCRIPTION 

pbmtocmuwm readsa portable bitmap as input and producesa C M U window manager bitmap asoutput. 
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SEE ALSO 

cmuwmtopbm(l), pbm(5) 

AUTHOR 

Copyright © 1989 by J ef Poskanzer 

15 April 1989 


pbmtoepsi 

pbmtoepsi— Convert a portable bitmap into an encapsulated PostScript-style preview bitmap 

SYNOPSIS 

pbmtoepsi [-bbonly] [pbmf i I e] 

DESCRIPTION 

pbmtoepsi reads a portable bitmap as input and produces an encapsulated PostScript-style bitmap as output. The output is 
not a standalone PostScript file; it isonly a preview bitmap, which can be included in an encapsulated PostScript file. N ote 
that there is no epsitopbm tool; thistransformation isone-way. 

This utility is a part of the pstoepsi tool by D oug C rabill (dgc@cs. purdue. edu). 

OPTIONS 

-bboniy 0 nly create a boundary box, don't fill it with the image. 

SEE ALSO 

pbm(5), pnmtops(l), psidtopgm(l) 

AUTHOR 

Copyright © 1988 byjef Poskanzer, modified by Doug Crabill 1992 

1992 


pbmtoepson 

pbmtoepson- Convert a portable bitmap into Epson printer graphics 

SYNOPSIS 

pbmtoepson [pbmf i I e ] 

DESCRIPTION 

pbmtoepson reads a portable bitmap as input and produces a file of Epson printer graphics as output. 
Note that there is no epsontopbm tool; thistransformation isone-way. 

SEE ALSO 

pbm(5) 

AUTHOR 

Copyright© 1991 byjohnTiller (tiiier@gaiois.msfc.nasa.gov) andJef Poskanzer 


4 January 1991 
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pbmtog3 

pbmtog3- Convert a portable bitmap into a G roup 3 fax file 

SYNOPSIS 

pbmtog3 [pbmf i I e ] 

DESCRIPTION 

pbmtog3 reads a portable bitmap as output and produces a G roup 3 fax file as input. 

REFERENCES 

The standard for Group 3 fax is defined in CCITT Recommendation T.4. 

BUGS 

Probably. 

SEE ALSO 

g3topbm(l), pbm(5) 

AUTHOR 

Copyright © 1989 by Paul H aeberli (<paui@manray.sgi.com>) 

2 October 1989 

pbmtogem 

pbmtogem-Con vert a portable bitmap into a GEM IMG file 

SYNOPSIS 

pbmtogem [pbmf i I e ] 

DESCRIPTION 

pbmtogem reads a portable bitmap as input and produces a compressed GEM IM G file as output. 

BUGS 

pbmtogem does not support compression of repeated lines 

SEE ALSO 

gemtopbm(l), pbm(5) 

AUTHORS 

Copyright © 1988 by David Beckemeyer and Jef Poskanzer 

11 July 1992 

pbmtogo 

pbmtogo— C onvert a portable bitmap into compressed G raphO n graphics 

SYNOPSIS 

pbmtogo [pbmf i t e ] 
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DESCRIPTION 

pbmtogo reads a portable bitmap as input and produces 2D compressed GraphOn graphics as output. Be sure to sdt up your 
GraphO n with the following modes: 8 bits/no parity; obeys no XO N /XO FF; nuls are accepted. These are all on the Comm 
menu. Also, remember to turn off tty post processing. N ote that there is no gotopbm tool. 

SEE ALSO 

pbm(5) 

AUTHORS 

Copyright © 1988,1989 byjef Poskanzer, M ichael H aberler, and Bo Thide 

24 N ovember 1989 


pbmtoicon 

pbmtoicon— Convert a portable bitmap into a Sun icon 

SYNOPSIS 

pbmtoicon [pbmf i Ie] 

DESCRIPTION 

pbmtoicon reads a portable bitmap as input and produces a Sun icon as output. 

SEE ALSO 

icontopbm(l), pbm(5) 

AUTHOR 

Copyright © 1988 byjef Poskanzer 

31 August 1988 


pbmtolj 

pbmtolj — Convert a portable bitmap into H P LaserJet format 

SYNOPSIS 

pbmtolj [-resolution N ][-float][-noreset] [pbmf i I e] 

DESCRIPTION 

pbmtolj reads a portable bitmap as input and produces H P Laserj et data as output. 

Notethatthereisno ljtopbmtool. 

OPTIONS 

-resolution Specifies the resolution of the output device in dpi. Typical values are 75,100,150,300. The default is 75. 

-float Suppresses positioning information. T he default isto write the sequence esc & 1 0 e to the output file 

-noreset Prevents pbmtolj from writing the resdt sequences to the beginning and end of the output file. 

All flags can be abbreviated to their shortest unique prefix. 


SEE ALSO 

pbm(5) 
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AUTHORS 

Copyright© 1988 byJef Poskanzerand M ichael Haberler. -float and -noreset optionsadded by Wim Lewis 

29 August 1988 


pbmtoln03 

pbmtoin03- Convert portable bitmap to D EC LN 03+Sixel output 

SYNOPSIS 

pbmtoln03 [-rltbf] p b mf i I e 

DESCRIPTION 

pbmtoin03 reads a portable bitmap as input and produces a D EC LN 03+Sixel output file. 

OPTIONS 

-i nn Usenn asvaluefor left margin (default 0). 

-r nn Usenn asvaluefor right margin (default 2400). 

-t nn Usenn asvaluefortop margin (default 0). 

-b nn Usenn asvaluefor bottom margin (default 3400). 

-f nn Usenn asvaluefor form length (default 3400). 

SEE ALSO 

pbm(5) 

AUTHOR 

Tim Cook, 26 February 1992 

7 May 1993 


pbmtolps 

pbmtoips- Convert a portable bitmap to PostScript 

SYNOPSIS 

pbmtolps [ -dpi n ] [ pbmfi I e ] 

DESCRIPTION 

pbmtoips reads a portable bitmap as input, and outputs PostScript. T he output PostScript uses I ines instead of the image 
operator to generate a (device-dependent) picture that will be imaged much faster. 

The PostScript path length is constrained to be less that 1000 points so that no limits are overrun on the Apple LaserWriter 
and (presumably) no other printers 

SEE ALSO 

pgmtops(l), ppmtops(l), pbm(5) 

AUTHOR 

George Phillips (<ph±iiips@cs. ubc. ca>) 
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pbmtomacp 

pbmtoinacp— Convert a portable bitmap into a M acPaint file 

SYNOPSIS 

pbmtomacp [ -1 left ] [ - r r i ght ] [ -b bottom] [ - t t op ] [pbmf i I e ] 

DESCRIPTION 

pbmtomacp reads a portable bitmap as input. If no input file isgiven, standard input is assumed. Produces a M acPaint file as 
output. 

The generated file is only the data fork of a picture. You will need a program such asmcvert to generate a M acbinary ora 
BinH ex file that containsthenecessary information to identify thefile as a PNTG file to M acOS. 

OPTIONS 

Left, ri ght, bottom, and t op let you defi ne a square i nto thePBM file which must be converted. Default isthe whole file. If 
the file is too large for a M acPaint file the bitmap is cut to fit from (i eft, top). 

BUGS 

Thesourcecodecontainscommentsin alanguage other than English. 

SEE ALSO 

ppmtopict(l), macptopbm(l), pbm(5), mcvert(l) 

AUTHOR 

Copyright © 1988 by Douwevan der Schaaf (... tmcvaxiuvapsyivdschaaf) 

31 August 1988 


pbmtomgr 

pbmtomgr- Convert a portable bitmap into an M G R bitmap 

SYNOPSIS 

pbmtomgr [pbmf i I e ] 

DESCRIPTION 

pbmtomgr reads a portable bitmap as input and produces an M G R bitmap as output. 

SEE ALSO 

mgrtopbm(l), pbm(5) 

AUTHOR 

Copyright © 1989 byjef Poskanzer 


24 January 1989 
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pbmtopgm 

pbmtopgm- Convert portable bitmap to portable graymap by averaging areas 

SYNOPSIS 

pbmtopgm <width><height> [pbmfile] 

DESCRIPTION 

pbmtopgm reads a portable bitmap as input and outputs a portable graymap created by averaging the number of pixels within a 
sample area of width by height around each point, pbmtopgm is si milar to a special case of ppmoonvoi. A ppmsmooth step maybe 
needed after pbmtopgm. 

pbmtopgm hasthe effect of antialiasing bitmaps that contain distinct linefeatures. 

SEE ALSO 

pbm(5) 

AUTHOR 

Copyright© 1990 by Angus Duggan. Copyright© 1989 byjef Poskanzer. 

NOTES 

pbmtopgm works best with odd sample widths and heights 

pbmtopi3 

pbmtopi3— C on vert a portable bitmap i nto an Atari D egas P13 fi le 

SYNOPSIS 

pbmtopi3 [pbmfile] 

DESCRIPTION 

pbmtopi3 reads a portable bitmap as input and produces an Atari Degas PI 3 file as output. 

SEE ALSO 

pi3topbm(l), pbm(5), ppmtopil(l), piltoppm(l) 

AUTHOR 

Copyright© 1988 byDavidBeckemeyer (bdtrdavidj andJefPodcanzer. 

11 March 1990 


pbmtopk 

pbmtopk- Convert a portable bitmap into a packed (PK) format font 

SYNOPSIS 

pbmtopk pkflie].pk] tfmfile[.tfm] resolution [-s designsize] [-p num param...] 
[-C cod-ingscheme] [-F family] ]-f optfile] [-c num] [-W width] [-H height] 

[-D depth] [-1 ital] ]-h horiz] ]-v vert] ]-x xoff] ]-y yoff] [pbmfile]... 



pbmtoplot 


365 


DESCRIPTION 

pbmtopk reads portable bitmaps as input and produces a packed (PK) font file and aTFM (TeX font metric) file as output. 
The resolution parameter indicates the resolution of the font, in dots per inch. If the filename - isused for any of the 
filenames, the standard input stream (or standard output, where appropriate) will be used. 


OPTIONS 


-f optfi I e 



-D depth 


Sets the design size of the font, in TeX's points (72.27 pointsto the inch). The default design size is i. The 
TFM parameters are given as multiples of the design size. 

Sets the first num font parameters for the font. The first seven parameters are the slant, interword spacing, 
interword space stretchabi lity, interword space shrinkability, x-height, quad width, and post-sentence extra 
space of the font. M ath and symbol fonts may have more parameters; see The TeXbook for a list of these. 
Reasonable default values are chosen for parameters that are not specified. 
Sdtsthecodingschemecommentin theTFM file. 

Sdts the font family comment in theTFM file. 

Reads thefile opt f i i e , which should contain a line of theform: 

ThePBM files specified by the filename parameters are inserted consecutively in the font with the 
specified attributes If any of the attributes are omitted, or replaced with *, a default value will be 
calculated from the size of the bitmap. The settings of the-w, -h, -d, -i, -h, -v, -x, and -yoptionsdo not 
affect characters created in thisway. Thecharacter number can be changed by including a line starting 
with =, followed by the new number. Lines beginning with % or# are ignored. 

Sdts the character number of the next bitmap encountered to n u m. 

SdtstheTFM width of the next character to width (in design size multiples). 

SdtstheTFM height of the next character to he i g ht (in design size multiples). 

SdtstheTFM depth of the next character to depth (in design size multiples). 

Sdts the italic correction of the next character to i tai (in design size multiples). 

Sdts the horizontal escapement of the next character to im i z (in pixels). 

Sdts the vertical escapement of the next character to vert (in pixels). 

Sdts the horizontal offset of the next character to xoff (in pixels). 

Sets the vertical offset of the next character toyoff (in pixels, from the top row). 


SEE ALSO 

pktopbm(l), pbm(5) 


AUTHOR 

Adapted from Tom Rokicki'spxtopk by Angus Duggan (ajcd@dcs.ed.ac.uk). 


6 August 1990 


pbmtoplot 

pbmtoplot- Convert a portable bitmap into a U NIX piot(5) file 

SYNOPSIS 

pbmtoplot [pbmf i I e ] 

DESCRIPTION 

pbmtoplot reads a portable bitmap as input and producesaUN IX plot file. 
Note that there is no piottopbmtool;thistransforrnation isoneway. 
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SEE ALSO 

pbm(5), plot(5) 

AUTHOR 

Copyright© 1990 by Arthur David Olson. 

1 September 1990 


pbmtoptx 

pbmtoptx— Convert a portable bitmap into Printronix printer graphics 

SYNOPSIS 

pbmtoptx [pbmf i I e] 

DESCRIPTION 

pbmtoptx reads a portable bitmap as input and produces a file of Printronix printer graphics as output. 

Note that there is no ptxtopbm tool; this transformation is one-way. 

SEE ALSO 

pbm(5) 

AUTHOR 

Copyright© 1988 byjef Poskanzer 

31 August 1988 


pbmtoxl0bm 

pbmtoxi 0 bm— Convert a portable bitmap into an X10 bitmap 

SYNOPSIS 

pbmtoxl0bm [pbmf i I e ] 

DESCRIPTION 

pbmtoxi 0 bm reads a portable bitmap as input and produces an X10 bitmap as output. This older format is maintained for 
compatibility. 

N otethat there is no xi 0 bmtopbm tool because xbmtopbm can read both Xll and X10 bitmaps. 

SEE ALSO 

pbmtoxbm(l), xbmtopbm(l), pbm(5) 

AUTHOR 

Copyright© 1988 byjef Poskanzer. 


31 August 1988 
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pbmtoxbm 

pbmtoxbm— Convert a portable bitmap into an Xll bitmap 

SYNOPSIS 

pbmtoxbm [ p b mf i I e ] 

DESCRIPTION 

pbmtoxbm reads a portable bitmap as input and produces an Xll bitmap as output. 

SEE ALSO 

pbmtox10bm(l), xbmtopbm(l), pbm(5) 

AUTHOR 

Copyright © 1988 byJef Poskanzer. 

31 August 1988 

pgmtoybm 

pgmtoybm— Convert a portable bitmap into a Bennet Yee "face;’ file 

SYNOPSIS 

pbmtoybm [pbmfiIe ] 

DESCRIPTION 

pgmtoybm reads a portable bitmap as input and produces as output a file acceptable to the face and xbm programs by Bennet 
Y ee( bsy+@cs.cmu.edu). 

SEE ALSO 

ybmtopbm(l), pbm(5), face(l), face(5), xbm(l) 

AUTHORS 

Copyright © 1991 byJamieZawinski and Jef Poskanzer. 

6 March 1990 

pbmtozinc 

pbmtozinc— Convert a portable bitmap into a Zinc bitmap 

SYNOPSIS 

pbmtozinc [pbmf i Ie] 

DESCRIPTION 

pbmtozinc reads a portable bitmap as input and produces a bitmap in theformat used by the Zinc I nterface Library (Zi L) 
version 1.0 as output. 

SEE ALSO 

pbm(5) 
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AUTHORS 

Copyright © 1988 by Jams Darrel I M cCauley (jdm5548@diamond.tamu.edu) and Jef Poskanzer. 


2 N ovember 1990 


pbmupc 

pbmupc— C reate a U niversal Product C ode bitmap 

SYNOPSIS 

pbmupc [-si! -s 2 ] type manufac product 

DESCRIPTION 

pbmupc generats a Universal Product Code symbol. T hethree arguments are: a one-digit product type, a five-digit manufac¬ 
turer code, and a five-digit product code For example, 0 72890 00011 isthecodefor H eineken. 

As presently configured, pbmupc producs a bitmap 230 bits wide and 175 bits high. The size can be altered by changing the 
defins at the beginning of the program, or by running the output through pnmeniarge or pnmscaie. 

OPTIONS 

The-si and -s2 flags select the style of UPC to generate. The default, -si, looksmoreor lesslikethis 


0||12345| 


|67890|]5 


The other style -s2, puts the product type digit higher up, and doesn't display the checksum digit: 


SEE ALSO 

pbm(5) 

AUTHOR 

Copyright © 1989 byJef Poskanzer. 


14 M arch 1989 


pcxtoppm 

pcxtoppm- Convert a PCX file into a portable pixmap 

SYNOPSIS 

pcxtoppm[pc*fiI e ] 

DESCRIPTION 

pcxtoppm reads a PCX file as input and produces a portable pixmap as output. 
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SEE ALSO 

ppmtopcx(l), ppm(5) 

AUTHOR 

Copyright © 1990 by M ichael Davidson. 

9 April 1990 


pfbtops 

pfbtops— T ranslate a PostScript font in PFB format to ASC11 

SYNOPSIS 

pfbtops [ pf b _ fiI e ] 

DESCRIPTION 

pfbtops translates a PostScript font in PFB format to ASCII. If pf b_ftie is omitted, the PFB filewill be read from the 
standard input. The ASC 11 format PostScript font will be written on the standard output. PostScript fonts for M S-DOS are 
normally supplied in PFB format. 

The resulting ASCII format PostScript font can beused with groff. It must first be listed in /usr/iib/groff/font/devps/ 
download. 


SEE ALSO 

grops(l) 


Groff Version 1.09, 6 August 1992 


pgmbentley 

pgmbentiey — Bentleyize a portable graymap 

SYNOPSIS 

pgmbentley [pgmfile] 

DESCRIPTION 

pgmbentley reads a portable graymap as input, performs the Bentley Effect, and writes a portable graymap as output. 

The Bentley Effect is described in Beyond Photography by FI olzmann, Chapter 4, photo 4. It's a vertical smearing based on 
brightness. 

SEE ALSO 

pgmoil(l), ppmrelief(1), pgm(5) 

AUTHOR 

Copyright © 1990 by W ilson Bent (whb@hoh- 2 .att.com). 


11 January 1991 



Parti: User Commands 


370 


pgmcrater 

pgmcratei — C reate cratered terrain by fractal forgery 

SYNOPSIS 

pgmcrater [-number n ][-height|-ysize s ][-width!-xsize s [[-gamma g] 

DESCRIPTION 

pgmcrater creates a portable graymap that mimics cratered terrain. The graymap is created by simulating the impact of a 
given number of craters with random position and size then rendering the resulting terrain elevations based on a light source 
shining from one side of the screen. The size distribution of the craters is based on a power law that results in many more 
small craters than large ones. T he number of craters of a given size varies as the reciprocal of the area as described on pages 31 
and 32 of T he SaenceOf Fractal Images edited by H .0. Peitgen and D. Saupe( New York: Springer-Verlag, 1988). Cratered 
bodies in the solar system are observed to obey this relationship. Theformula used to obtain crater radii governed by this law 
from a uniformly distributed pseudorandom sequence was developed by Rudy Rucker. 

H igh resolution images with large numbers of craters often benefit from being piped through pnmsmooth. The averaging 
performed by this process eliminates some of thejagged pixelsand lendsa mellow "telescopic image" feel to the overal I 
picture. 

OPTIONS 

-number n Causes n craters to be generated. If no -number specification is given, 50,000 craters will be generated. Don’t 
expect to see them all! For every large crater, there are many, many more tiny ones that tend simply to erode the landscape. 

I n general, the more craters you specify, the more realistic the result; ideally, you want the entire terrai n to have been 
extensively turned over again and again by cratering. H igh-resolution images containing five to ten million craters are 
stunning but take quite a while to create 

-height height Sets the height of the generated i mage to h e i g h t pixels. The default height is 256 pixels 

-width wi dth Setsthe width of the generated imagetowi dth pixels The default width is256 pixels. 

-xsize wi dth Setsthe width of the generated imagetowi dth pixels The default width is256 pixels. 

-ysize height Sets the height of the generated i mage to h e i g h t pixels. The default height is 256 pixels 

-gamma factor The specified factor isused to gamma correct the graymap in the same manner as performed by pnmgamma. 

The default value is i.0, which results in a medium contrast image. Values larger than 1 lighten the image 
and reduce contrast, while values less than 1 darken the image, increasing contrast. 

All flags can be abbreviated to their shortest unique prefix. 

BUGS 

The -gamma option isn't really necessary because you can achieve the same effect by piping the output from pgmcrater 
through pnmgamma. H owever, pgmcrater performs an internal gamma map anyway in the process of rendering the elevation 
array into a graymap, so there's no additional overhead in allowing a user-specified gamma. 

Real craters have two distinct morphologies pgmcrater simulates only small craters, which are hemispherical in shape 
(regardless of the incidence angle of the impacting body, as long as the velocity is sufficiently high). Large craters, such as 
Copernicus and Tycho on the moon, have a "walled plain" shape with a cross-section more like: 


Larger craters should really use this profile, including the central peak, and totally obliterate the preexisting terrain. 

SEE ALSO 

pgm(5), pnmgamma(l), pnmsmooth(l) 




pgmenhance 




AUTHOR 

John Walker 

Autodesk SA Avenue desChamps-M ontantsl4b 
CH-2074 MARIN 

Sui ss^ Sch wei z/ Svi zzeral Svizra/ Swi tzerl an d 
Usenet: kelvin@Autodesk.com 

Fax: 038/33 88 15 

Voice 038/33 76 33 

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is 
hereby granted, without any conditions or restrictions. T hissoftware is provided "as is" without express or implied warranty. 
PLUG WARE! If you like this kind of stuff, you may also enjoy J ames G leick's "Chaos- The Software" for M S-DOS, 
available for $59.95 from your local software store or directly from Autodesk, Inc., Attn: Science Series, 2320 M arinship 
Way, Sausalito, CA 94965, USA. Telephone: 800-688-2344 toll-free or, outside the U.S. (415) 332-2344 Ext 4886. Fax: 
415-289-4718. "C haos- T he Software" includes a more comprehensive fractal forgery generator that creates three- 
dimensional landscapes as well as clouds and planets, plus five more modules that explore other aspects of Chaos. The user 
guide of more than 200 pages includes an introduction byj ames G lei ck and detailed explanations by Rudy Rucker of the 
mathematics and algorithms used by each program. 

15 October 1991 


pgmedge 

pgmedge— Edge detect a portable graymap 

SYNOPSIS 

pgmedge [pgmfile] 

DESCRIPTION 

pgmedge reads a portable graymap as input, outlines theedges, and writes a portable graymap asoutput. Piping theresult 
through pgmtopbm -threshold and playing with the threshold value will give a bitmap of theedges. 

The edge detection technique used is to take the Pythagorean sum of two Sobel gradient operators at 90 degrees to each 
other. For more details see Digital I mage Processing by Gonzalez and Wintz, Chapter 7. 

SEE ALSO 

pgmenhance(l), pgmtopbm(l), pgm(5), pbm(5) 

AUTHOR 

Copyright © 1991 byJefPo&anzer. 

4 February 1990 


pgmenhance 

pgmenhance- Edgeenhancea portable graymap 

SYNOPSIS 




[-N] [pgmfile] 
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DESCRIPTION 

pgmenhance readsa portable graymap asinput, enhances the edges, and writes a portable graymap as output. 

The edge enhancing technique is taken from Philip R. Thompson'sxim program, which took it from section 6 of Digital 
Halftones by Dot Diffusion, D. E. Knuth,/4CM Transaction on GraphicsM ol. 6, No. 4, October 1987, which in turn got it 
from two 1976 papers by J. F. Jarviset. al. 

OPTIONS 

The optional -n flag should be a digit from 1 to 9.1 isthe lowest level of enhancement, 9 isthe highest; the default is 9. 

SEE ALSO 

pgmedge(l), pgm(5), pbm(5) 

AUTHOR 

Copyright © 1989 by J ef Poskanzer. 

13 January 1989 


pgmhist 

pgmhist— Print a histogram of the values in a portable graymap 

SYNOPSIS 

pgmhist [pgmf i I e ] 

DESCRIPTION 

pgmhist reads a portable graymap as input and printsa histogram of the gray values. 

SEE ALSO 

pgmnorm(l), pgm(5), ppmhist(l) 

AUTHOR 

Copyright © 1989 byjef Poskanzer 

28 February 1989 


pgmkernel 

pgmkernei— Generate a convolution kernel 

SYNOPSIS 

pgmkernel [ -weight w ] width [ height ] 

DESCRIPTION 

pgmkernel generates a portable graymap array of sizewidth x height (or width xltith ifheight is not specified) to be used as 
a convolution file by pnmconvoi. The data in theconvolution array K are computed according to the formula: 

K0.il=- - - 


1 twVfl-wtdWEJ 1 t 1 



pgmnorm 


F] 

wherew is a coefficient specified via the -weight flag, and wi dt h and hei g ht aretheX and Y filter sizes 
Theoutput PGM file is always written out in ASCII format. 

OPTIONS 

The optional -weight flag should be a real number greater than -1. The default value is6.o. 

BUGS 

The computation time is proportional to width * height. This increases rapidly with the increase of the kernel size. A better 
approach could beto use a FFT in these cases 

SEE ALSO 

pnmconvol(l), pnmsmooth(l) 

AUTHOR 

Alberto Accomazzi (alberto@cfa.harvard.edu) 

10 D ecember 1992 


pgmnoise 

pgmnoise— C reate a graymap made up of white noise 

SYNOPSIS 

pgmnoise width height 

DESCRIPTION 

pgmnoise creates a portable graymap that is made up of random pixels with gray values in the range of 0 to pgmjiaxmaxval 
(dependsonthecompilation, either 255 or 65535). The graymap has a size of width * height pixels. 

SEE ALSO 

pgm(5) 

AUTHOR 

Copyright © 1993 by Frank N eumann 

16 N ovember 1993 


pgmnorm 

pgmnorm- N ormalizethecontrast in a portable graymap 

SYNOPSIS 

pgmnorm[-bpercent N | -bvalue N][-wpercent N ] -wvalue N][pgmfile] 

DESCRIPTION 

pgmnorm reads a portable graymap as input; normalizes the contrast by forcing the lightest pixels to white, the darkest pixels to 
black, and linearly rescaling the ones in between; and produces a portable graymap as output. 

OPTIONS 

By default, the darkest two percent of all pixels are mapped to black, and the lightest one percent are mapped to white. You 
can override these percentages by using the -bpercent and -wpercent flags, or you can specify the exact pixel valuesto be 
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mapped by using the -bvaiue and -wvaiue flags Appropriate numbers for the flags can begotten from the pgmhist tool. If 
youjust want to enhance the contrast, then choose values at elbows in the histogram; for example, if value 29 represents3 
percent of the image but value 30 represents 20 percent, choose30 for bvaiue. If you want to lighten the image then set 
bvaiue to 0 and just fiddle with wvaiue; similarly, to darken the image set wvaiue to maxvai and play with bvaiue. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pgmhist(l), ppmnorm(l), pgm(5) 

AUTHOR 

Partially based on the fbnorm filter in M ichael M auldin's "Fuzzy Pixmap" package 
Copyright© 1989 byjef Poskanzer. 

28 February 1989 


pgmoil 

pgmoii— Turn a portablegraymap into an oil painting 

SYNOPSIS 

pgmoil [-n N ] [pgmf i I e] 

DESCRIPTION 

pgmoii reads a portable graymap as input, does an "oil transfer," and writes a portable graymap as output. 

The oil transfer is described in Beyond Photography by Holzmann, Chapter 4, photo 7. It's a sort of localized smearing. 

OPTIONS 

The opti onal -n flag controls the size of the area smeared .The default value is 3. 

BUGS 

Takesalong time to run. 

SEE ALSO 

pgmbentley(l), ppmrelief(l), pgm(5) 

AUTHOR 

Copyright© 1990 by Wilson Bent (whb@hoh-2.att.com). 

11 January 1991 


pgmramp 

pgmramp— G enerate a grayscale ramp 

SYNOPSIS 

pgmramp -lr|-tb | -rectangle(-ellipse width height 

DESCRIPTION 

pgmramp generates a graymap of the specified size containing a black-to-white ramp. T hese ramps are useful for multiplying 
with other images, using the pnmarith tool. 
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OPTIONS 

-ir A left to right ramp 

-tb A top to bottom ramp 

-rectangle A rectangular ramp 

-ellipse An elliptical ramp 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pnmarith(l), pgm(5) 

AUTHOR 

Copyright © 1989 byJef Poskanzer. 

24 N ovember 1989 


pgmtexture 

pgmtexture— C alculate textural features on a portable graymap 

SYNOPSIS 

pgmtexture [ -d d ] [pgmf i I e ] 

DESCRIPTION 

pgmtexture reads a portable graymap as input. Calculates textural features based on spatial dependence matrices at 0,45, 90, 
and 135 degreesfor a distanced (default = i). Textural features include 

(1) Angular Second M oment 

(2) Contrast 

(3) Correlation 

(4) Variance 

(5) I nverse D ifference M oment 

(6) Sum Average 

(7) Sum Variance 

(8) Sum Entropy 

(9) Entropy 

(10) Difference Variance 

(11) Difference Entropy 

(12,13) Information M easures of Correlation 
(14) Maximal Correlation Coefficient 

Algorithm taken from "Textural Features for I mage Classification,"/EEE Transactions on Systems M an, and Cybertinetics, 

R.M . H aralick, K. Shanmugam, and I. Dinstein, 1973. SM C-3(6):610-621. 

BUGS 

The program can run incredibly slowly for large images (larger than 64x64) and command-line options are limited. The 
method for finding the maximal correlation coefficient, which requires finding the second largest eigenvalue of a matrix Q, 
does not always converge. 

REFERENCES 

IEEE Transadionson Systems M an, and Cybertinetics SM C-3(6):610-621. 
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SEE ALSO 

pgm(5), pnmcut(l) 

AUTHOR 

Copyright © 1991 by Texas Agricultural Experiment Station, employer-for-hire of James Darrell M cCauley. 

22 August 1991 


pgmtofs 

pgmtofs— C onvert portable graymap to U senix F aceSaver format 

SYNOPSIS 

pgmtofs [ p g mf i t e ] 

DESCRIPTION 

pgmtofs reads a portable graymap as input. Produces U senix FaceSaver format as output. 

FaceSaver is a registered trademark of M dtron Computerware Ltd. of Oakland, CA. 

SEE ALSO 

fstopgm(l), pgm(5) 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

18 May 1990 


pgmtolispm 

pgmtoiispm—Convert a portable graymap into Lisp machine format 

SYNOPSIS 

pgmtolispm [pgmfile] 

DESCRIPTION 

pgmtolispm reads a portable graymap as input and produces a Lisp machine bitmap as output. 

This is the file format read by the tv: read-bit-array-file function on Tl Explorer and Symbolics Lisp machines 
Given a PGM (instead of aPBM), a multiplane image will be output. This is probably not useful unless you havea color 
Lisp machine. 

M ultiplane bitmaps on Lisp machines are color; buttheiispm image file format does not include a colormap, so it must be 
treated as a graymap instead. This is unfortunate. 

SEE ALSO 

lispmtopgm(l), pgm(5) 

BUGS 

Output width isalways rounded up to the nearest multiple of 32; this might not always be what you want, but it probably is 
(arrays that are not modulo 32 cannot be passed to the lispm bitblt function, and thus cannot easily be displayed on the screen). 
N o color. 
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AUTHOR 

Copyright© 1991 byJamieZawinski andJef Poskanzer. 


6 March 1990 


pgmtopbm 

pgmtopbm— Convert a portable graymap into a portable bitmap 

SYNOPSIS 

pgmtopbm [-floyd|-fsi-threshold i-hilbert |-ditherSi-d8|-cluster3 
i-c3!-cluster^-c4 |-clusten8|-c8][-value v a I ][-clump si ze][pgmfi I e] 

DESCRIPTION 

pgmtopbm reads a portable graymap as input and produces a portable bitmap as output. 

Note that there is no pbmtopgm converter because any pgm program can read PBM files automagically. 

OPTIONS 

The default quantization method isboustrophedonic F loyd-Stei n berg error diffusion (-fioyd or -fs). Also available are 
simplethresholding ( -threshold); Bayer's ordered dither (-dithers) with a 16x16 matrix; and three different sizes of 45- 
degree clustered-dot dither (-clusters, -cluster, -clusters). A space-filling curve halftoning method using the H ilbert 
curveisalso available, ( hiibert). 

Floyd-Steinberg will almost always give the best looking results; however, looking good is not always what you want. For 
instance, thresholding can be used in a pipeline with thepnmconvoi tool, for tasks like edge and peak detection. And 
clustered-dot dithering gives a newspaper-like look, a useful special effect. The -value flag alters the thresholding value for 
Floyd-Steinberg and simple thresholding. It should be a real number between 0 and 1. Above 0.5 means darker images; 
below 0.5 means lighter. 

The Hilbert curve method isuseful for processing images before display on devicesthat do not render individual pixels 
distinctly (like laser printers). T hisdithering method can give better results than the dithering usually doneby the laser 
printers themselves. The -clump flag altersthe number of pixelsin adump. This is usually an integer between 2and 100 
(defaults). Smaller clump sizes smear the image less and are less grainy, but seem to loose some grayscale linearity. Typically, 
a PGM image will have to be scaled to fit on a laser printer page (2400 x 3000 pixels for an A4 300dpi page), and then 
dithered to a PBM image before being con verted to a PostScript file. A printing pipeline might look something like this 

pnmscale -xyslze 2400 3000 image.pgm ] pgmtopbm -hil | pnmtops -scale 0.25 image.ps 

All flags can be abbreviated to their shortest unique prefix. 

REFERENCES 

The only reference you need for this stuff isDigtal Halftoningby Robert Ulichney, M IT Press ISBN 0-262-21009-6. 

The H ilbert curve space filling method istaken from "D igital H alftoning with Space Filling Curves" by Luiz Velho, 

C omputer G raphicsM olume 25, Number 4, proceedings of SI GRAPH '91, page81. ISBN 0-89791-436-8 

SEE ALSO 

pbmreduce(l), pgm(5), pbm(5), pnmconvol(l), pnmscale(l), pnmtops(l) 

AUTHOR 

Copyright © 1989 byJef Poskanzer. 


26 July 1988 
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pgmtoppm 

pgmtoppm— Colorize a portable graymap into a portable pixmap 

SYNOPSIS 

pgmtoppm colorspec [pgmfi I e] 
pgmtoppm colorspecl -colorspec2 [pgmfile] 
pgmtoppm -map mapfile [pgmfile] 

DESCRIPTION 

pgmtoppm reads a portable graymap as input, colorizes it by multiplying the gray values by specified color or colors, and 
produces a portable pixmap as output. 

If only one color is specified, black in the PGM file stays black and white in the PGM file turns into the specified color in 
the PPM file If two colors (separated by a hyphen) are specified, then black gets mapped to the first color and white gets 
mapped to the second. 

The color can be specified in five ways 

■ A name, assuming that a pointer to an X 11-style color names file wascompiled in. 

■ An X 11-style hexadecimal specifier: rgb: r/g/b, where r, g, and b are each 1- to 4-digit hexadecimal numbers. 

■ An X 11-style decimal specifier: rgbi:r/g/b, where r, g, and b are floating-point numbers between 0 and 1. 

■ For backwards Compatibility, an Old-Xll-Style hexadecimal number: #rgb, #rrggbb, #rrrgggbbb, Or#rrrrggggbbbb. 

■ For backwards compatibility, a triplet of numbers separated by commas r,g,b, where r, g, and b are floating-point 
numbers between 0 and 1. (Thisstyle was added before M IT came up with thesimilar rgbi style) 

Also, the -map flag Idts you specify an entire colormap to be used. The mapfile is just a PPM file; it can beany shape all that 
mattersisthecolorsin it and their order. In this case black gets mapped to the first color in the mapfile, and white gets 
mapped to the last. 

SEE ALSO 

rgb3toppm(l), ppmtopgm(l), ppmtorgb3(l), ppm(5), pgm(5) 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

11 January 1991 


piltoppm 

piitoppm- Convert an Atari Degas PI 1 into a portable pixmap 

SYNOPSIS 

piltoppm [pi lfiI e] 

DESCRIPTION 

piitoppm reads an Atari D egas P11 file as input and produces a portable pixmap as output. 

SEE ALSO 

ppmtopil(1), ppm(5), pi3topbm(l), pbmtopi3(l) 

AUTHORS 

Copyright© 1991 by Steve Belczyk (seb3@gte.com) and Jef Poskanzer. 


19 July 1990 
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pi3topbm 

pi3topbm— Convert an Atari D egas PI 3 file into a portable bitmap 

SYNOPSIS 

pi3topbm [pi 3fiI e ] 

DESCRIPTION 

pi3topbm reads an Atari D egas PI3 fileasinput. Produces a portable bitmap as output. 

SEE ALSO 

pbmtopi3(l), pbm(5), piltoppm(l), ppmtopil(1) 

AUTHORS 

Copyright© 1988 by David Beckemeyer (bdtidavid) and DiomidisD. Spinellis. 

11 March 1990 


picttoppm 

picttoppm— Convert a M acintosh PICT file into a portable pixmap 

SYNOPSIS 

picttoppm [-verbose][-fullres][-noheader][-quickdraw][-fontdirf i I e] [pi ctf i I e] 


DESCRIPTION 

picttoppm reads a PICT file (version 1 or 2) and outputs a portable pixmap. Useful as the first step in converting a scanned 
image to something that can be displayed on UN IX. 


OPTIONS 

-fontdir file 

-fullres 

-noheader 

-quickdraw 

-verbose 


Make the list of BDF fonts in fi i e avail able for use by pict-toppm when drawing text. For the format of 
the fontdir file seethe "fontdir File Format" subsection. 

Forceany images in the PICT file to be output with at least their full resolution.A PICT file may indicate 
that a contained image is to be scaled down before output. This option forces images to retain their sizes 
and prevent information loss Use of this option disables all PICT operations except images 
Do not skip the 512-byte header that ispresent on all PICT files This is useful when you have PICT data 
that was not stored in thedatafork of a PICT file 

Execute only pure quickdraw operations In particular, turn off the interpretation of special PostScript 
printer operations 

T urnson verbose mode which prints a whole bunch of information that only picttoppm hackers really 
care about. 


BUGS 

The PICT file format is a general drawing format, picttoppm does not support all the drawing commands but it does have 
full support for any image commands and reasonable support for line, rectangle, polygon, and text drawing. It is useful for 
converting scanned images and some drawing conversion. 

M emory is used very liberally with at least six bytes needed for every pixel. Large bitmap PICT files will likely run your 
computer out of memory. 
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fontdir FILE FORMAT 

picttoppm hasa built-in default font and your local installer probably provided adequate extra fonts You can point picttoppm 
at more fonts that you specify in a font directory file. Each line in the file is either a comment line which must begin with#, 
or font information. The font information consists of four whitespace separated fields. Thefirst isthefont number, the 
second isthefont size in pixels the third isthefont style and thefourth isthenameof a BD F file containing thefont. The 
BD F format is defined by the X Window System and is not described here. 

Thefont number indicates the type face H ere is a list of known font numbers and their faces 
0 Chicago 

1 Application font 

2 New York 

3 Geneva 

4 M onaco 

5 Venice 

6 London 

7 Athens 

8 San Francisco 

9 T oronto 

11 Cairo 

12 LosAngeles 

20 Times Roman 

21 H elvetica 

22 Courier 

23 Symbol 

24 Taliesin 

Thefont style indicates a variation on thefont. M ulti pie variations may apply to a font and thefont style is the sum of the 
variation numbers which are 

1 Boldface 

2 Italic 

4 Underlined 

8 Outlined 

i6 Shadow 

32 Condensed 

64 Extended 

Obviously, thefont definitions are strongly related to the Macintosh. More font numbers and information about fonts can 
be found in M acintosh documentation. 

SEE ALSO 

Inside Macintosh volumes 1 and 5, ppmtopict(l), ppm(5) 

AUTHOR 

Copyright ©1993 George Phillips 


29 N ovember 1991 
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pjtoppm 

pjtoppm— Convert an HP PaintJ et file to a portable pixmap 

SYNOPSIS 

pjtoppm [pai ntj et ] 

DESCRIPTION 

pjtoppm reads an H P PaintJet file as input and converts it into a portable pixmap. This was a quick hack to save some trees, 
and it only handles a small subset of the paint jet commands In particular, it will only handle enough commands to convert 
most raster image files 

REFERENCES 

HP PaintJet XL Color GraphicsPrinter U ser'sGuide 

SEE ALSO 

ppmtopj(1) 

AUTHOR 

Copyright© 1991 by C hristos Zoulas. 

14 July 1991 

pktopbm 

pktopbm— Convert packed (PK) format font into portable bitmap(s) 

SYNOPSIS 

pktopbm pkfilej.pk] [-c n u m] p b mf i I e ... 

DESCRIPTION 

pktopbm reads a packed (PK) font file as input and produces portable bitmaps as output. If the filename"-" is used for any of 
thefilenames the standard input stream (or standard output where appropriate) will be used. 

OPTIONS 

-c niim Sdts the character number of the next bitmap written to num. 

SEE ALSO 

pbmtopk(l), pbm(5) 

AUTHOR 

Adapted from Tom Rokicki'spxtopk by Angus Duggan (ajcd@dcs.ed.ac.uk). 

6 August 1990 

pnmalias 

pnmalias— Anti alias a portable anymap. 

SYNOPSIS 


pnmalias [-bgcolor color ][-fgcolor color][-bonly][-fonly][-balias][-falias] 
[ -weight w] [pnmf i I e ] 
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DESCRIPTION 

pnmaiias reads a portable anymap as input and applies antialiasing to background and foreground pixels. If the input file isa 
portable bitmap, the output antialiased image is promoted to a graymap, and a message is printed informing the user of the 
change in format. 

OPTIONS 

-bgcolor coi orb. Set the background color to coi orb, and the foreground to color to c o i o r f. Pixels with these values 

-fgcoior coi or f will be anti aliased. By default, the background color is taken to be black, and foreground color is 

assumed to be white The colors can be specified in five ways: 

■ A name, assuming that a pointer to an X 11-style color names file wascompiled in. 

■ An X 11-style hexadecimal specifier: rgb: r/g/b, where r, g, and b are each 1- to 4-digit 
hexadecimal numbers. 

■ An X 11-style decimal specifier: rgbi: r/g/b, where r, g, and b are floating-point numbers 
between 0 and 1. 

■ For backwards compatibility, an old-X 11-style hexadecimal number: #rgb, #rrggbb, 
#rrrgggbbb, Or #rrrrggggbbbb. 

■ For backwards compatibility, a triplet of numbers separated by commas r,g,b, where r, g, 
and bare floating-point numbers between Oand 1. (Thisstyle was added before M IT came 
up with the similar rgbi style) 

Note that even when dealing with graymaps, background and foreground colors need to be specified in the fashion described 
in the preceding list. In this case, background and foreground pixel values are taken to be the value of the red component for 
the given color. 

-boniy, -foniy Apply antialiasing only to background (-boniy), or foreground (-fonly) pixels 

-baiias, -falias Apply antialiasing to all pixels surrounding background (-baiias), or foreground (-falias) pixels. 

By default, antialiasing takes place only among neighboring background and foreground pixels, 
-weight w Usew as the central weight for the aliasing filter, w must be a real number in the range 0 <w <1. 

The lower the value of w is the "blunder" the output image is. The default isw = 1/3. 

SEE ALSO 

pbmtext(l), pnmsmooth(l), pnm(5) 


AUTHOR 

Copyright© 1992 by Alberto Accomazzi, Smithsonian Astrophysical 0 bservatory. 


30 April 1992 


pnmarith 

pnmarith— Perform arithmetic on two portable anymaps 

SYNOPSIS 

pnmarith -add|-subtract|-multiply|-difference pnmf i I el pnmf i I e2 

DESCRIPTION 

pnmarith reads two portable anymaps as input, performs the specified arithmetic operation, and producesa portable anymap 
asoutput. Thetwo input anymaps must be the same width and height. 

The arithmetic is performed between corresponding pixels in thetwo anymaps, as if maxvai wasi . 0 , black waso.o, with a 
linear scale in between. Results that fall outside of [0.. 1) are truncated. 
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Theoperator -difference calculates the absolute value of 
pnmarith -subtract pnmfilel pnm- f i I e2 

In other words, no truncation is done. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pbmmask(l), pnmpaste(l), pnminvert(l), pnm(5) 

AUTHOR 

Copyright© 1989,1991 byJef Poskanzer. Lightly modified by M arcel W ijkstra (wijkstra@fwi.uva.nl). 

26 August 1993 


pnmcat 

pnmcat— C oncatenate portable anymaps 

SYNOPSIS 

pnmcat [-white|-black] -leftright]-lr [-j top|-j bottom] pnmfile pnmfile ... 
pnmcat [-white|-black] -topbottom]-tb [-jleft|-j right] pnmfile pnmfile ... 

DESCRIPTION 

pnmcat reads portable anymaps as in put, concatenates them either left to right or top to bottom, and produces a portable 
anymap as output. 

OPTIONS 

If the anymaps are not all thesame height (left-right) or width (top-bottom), the smaller ones have to be justified with the 
largest. By default, they get centered, but you can specify one side or the other with oneof the -j* flags So, -topbottom - 
jieft would stack the anymaps on top of each other, flush with the left edge 

The -white and -black flagsspecify which color to use to fill in the extra space when doing thisjustification. If neither is 

specified, the program makes a guess 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pnm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

12 March 1989 


pnmcomp 

pnmcomp— Composite two portable anymap files together 

SYNOPSIS 


pnmcomp [-invert][-xoffN] [-yoffN] [-alphapgmfile] overlay [pnm-input][pnm-output ] 
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DESCRIPTION 

pnmcomp reads in a portable anymap image and puts an overlay upon it, with optional alpha mask. The- aiphapgmfiie allows 
you to also add an alpha mask file to the compositing process; the range of max and min can be swapped by using the -invert 
option. The -xoff and -yoff argumentscan be negative allowing you to shift the overlay off the top corner of the screen. 

SEE ALSO 

pnm(5) 

AUTHOR 

Copyright© 1992 by David Koblas(kobias@mips.com). 

21 February 1989 


pnmconvol 

pnmconvoi— General mxn convolution on a portable anymap 

SYNOPSIS 

pnmconvol convol ut i onf i I e [pnmfi I e] 

DESCRIPTION 

pnmconvol reads two portable anymapsas input, convolves the second using the first, and writes a portable anymap asoutput. 
Convolution means replacing each pixel with a weighted average of the nearby pixels The weights and the area to average are 
determined by the convolution matrix. The unsigned numbers in theconvolution file are offset by -maxvai/2to make signed 
numbers, and then normalized, so theactual valuesin theconvolution file are only relative 
Here is a sample convolution file; it does a simple average of the nine immediate neighbors, resulting in a smoothed image 

P2 
3 3 


10 10 10 
10 10 10 
10 10 10 

To see how this works do the offset mentioned in the preceding paragraph: 10 -18/2 gives 1. The possible range of values is 
from 0 to 18, and after the offset that's-9 to 9. The normalization step makes the range-1 to 1, and the values gdt scaled 
correspondingly so they become 1/9— exactly what you want. T he equivalent matrix for 5x5 smoothing would have maxvai 
50 and be filled with 26 . 

Theconvolution file will usually be a graymap, so that the same convolution is applied to each color component. However, if 
you want to use a pixmap and do a different convolution to different colors, you can certainly do that. 

SEE ALSO 

pnmsmooth(l), pnm(5) 

AUTHOR 

Copyright© 1989,1991 by J ef Poskanzer. 


13 January 1991 
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pnmcrop 

pnmcrop— C rap a portable anymap 

SYNOPSIS 

pnmcrop [-white]-black][-left][-right][-top][-bottom] [pnmfi I e] 

DESCRIPTION 

pnmcrop reads a portable anymap as input, removes edges that are the background color, and produces a portable anymap as 
output. 

OPTIONS 

By default, it makes a guess as to what the background color is. You can override the default with the -white and -black flags 
Theoptions -left, -right, -top and -bottom restrict cropping to the sides specified. The default isto crop all sides of the 
image 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pnmcut(l), pnm(5) 

AUTHOR 

Copyright © 1989 byJef Poskanzer. 

25 February 1989 


pnmcut 

pnmcut — C ut a rectangle out of a portable anymap 

SYNOPSIS 

pnmcut x y width height [pnmfile] 

DESCRIPTION 

pnmcut reads a portable anymap as input, extracts the specified rectangle, and produces a portable anymap as output. The x 
and y can be negative in which case they are i nterpreted relative to the right and bottom of the anymap, respectively. 

SEE ALSO 

pnm(5) 

AUTHOR 

Copyright © 1989 by J ef Poskanzer. 

21 February 1989 

pnmdepth 

pnmdepth— Changethemaxvai in a portable anymap 

SYNOPSIS 


pnmdepth newmaxval [pnmfile] 
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DESCRIPTION 

pnmdepth reads a portable anymap as input, scales all the pixel values, and writes out the image with the new maxvai. Scaling 
the colors down to a smaller maxvai will result in some loss of information. 

Be careful of off-by-oneerrors when choosing the new maxvai. For instance if you want the color values to be five bits wide, 
use a maxvai Of31,not 32. 

SEE ALSO 

pnm(5), ppmquant(l), ppmdither(l) 

AUTHOR 

Copyright © 1989,1991 byJef Poskanzer. 

12 January 1991 


pnmenlarge 

pnmeniarge— Read a portable anymap and enlarge it N times 

SYNOPSIS 

pnmenlarge N [pnmf i I e ] 

DESCRIPTION 

pnmenlarge reads a portable anymap as input, replicates its pixels n times, and produces a portable anymap asoutput. 
pnmenlarge can only enlarge by integer factors The slower but more general pnmscaie can enlarge or reduce by arbitrary 
factors, and pbmreduce can reduce by integer factors but only for bitmaps 

If you enlarge by a factor of 3 or more you should probably add a pnmsmooth step; otherwise, you can see the original pixels 
in the resulting image 

SEE ALSO 

pbmreduce(l), pnmscale(l), pnmsmooth(l), pnm(5) 

AUTHOR 

Copyright © 1989 by J ef Poskanzer. 

26 February 1989 


pnmfile 

pnmf lie— D escribe a portable anymap 

SYNOPSIS 

pnmf ile [pnmf i t e ] ... 

DESCRIPTION 

pnmfiie reads one or more portable anymaps as input and writes out short descriptions of the image type size, and so on. 
This is mostly for usein shell scripts, so theformat is not particularly pretty. 

SEE ALSO 

pnm(5), file(l) 
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AUTHOR 

Copyright © 1991 byJef Poskanzer. 


9 January 1991 


pnmflip 

pnmfiip — Perform one or more flip operations on a portable anymap 

SYNOPSIS 

pnmflip [-leffright]-lr][-topbottom]-tb][-transpose]-xy][-rotate90]-r90]-ccw ] 

[-rotate270]-r270]-cw ][-rotatel80]-rl80][pnmf i I e ] 

DESCRIPTION 

pnmfiip reads a portable anymap as input, performs one or more flip operations in the order specified, and writes out a 
portable anymap. 

OPTIONS 

Theflip operations available are left for right (-leftright or -ir); top for bottom (-topbottom or -tb); and transposition (- 
transpose or -xy). I n addition, somecanned concatenations are available: -rotate9oor -ccwisequivalentto -transpose - 
topbottom; -rotate270 Or-cw is equivalent to -transpose -leftright; and -rotate180 is equivalent to -leftright -topbottom. 
All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pnmrotate(l), pnm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

25 July 1989 


pnmgamma 

pnmgamma- Perform gamma correction on a portable anymap 

SYNOPSIS 

pnmgamma value [pnmf i I e ] 

pnmgamma r edva I ue greenvalue bluevalue [pnmfile] 


DESCRIPTION 

pnmgamma reads a portable anymap as input, performsgamma correction, and produces a portable anymap as output. 

T he arguments specify what gamma value(s) to use A value of 1.0 leaves the image alone, less than 1 darkens it, and greater 
than 1 lightens it. 

SEE ALSO 

pnm(5) 

AUTHOR 

Copyright© 1991 by Bill Davidson and Jef Poskanzer. 


12 January 1991 
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pnmhistmap 

pnmhistmap— Draw a histogram for a PGM or PPM file 

SYNOPSIS 

pnmhistmap [-black][-white][-max N ][-verbose] [pnmf i I e] 

DESCRIPTION 

pnmhistmap reads a portable anymap as input, although bitmap (PBM) input produces an error message and no image and 
produces an image showing a histogram of the color (or gray) values in the input. A graymap (PGM ) input produces a 
bitmap output. A pixmap (PPM) input produces pixmap output with three overlaid histograms a red one for the red input, 
a green one for the green input, and a blue onefor the blue input. The output isfixed in size 256 pixels wide by 200 pixels 
high. 

OPTIONS 

-black Ignores the count of black pixelswhen scaling the histogram. 

-white Ignores the count of white pixels when scaling the histogram. 

The -black and -white options, which can be used separately or together, are useful for images with a large percentage of 
pixels whose value is zero or 255, which can cause the remaining histogram data to become unreadably small. Note that, for 
pixmap inputs, these options apply to all colors if, for example, the input hasa large number of bright-red areas you will 
probably want to use the -white option. 

-max n Forcethescalingof thehistogram to useN as the largest-count value. T his is useful forinputswith alarge 
percentage of single-color pixels that are not black or white. 

-verbose Report the progress of making the histogram, including the largest-count value used to scale the output. 

All flags can be abbreviated to their shortest unique prefix. 

BUGS 

Assumes maxvai is always 255.1 mages with a smaller maxvai will only use the lower-value side of the histogram. This can be 
overcome either by piping the input through pnmdepth 255 or by cutting and scaling the lower-value side of the histogram. 

N ether is a particularly elegant solution. 

Should allow the output size to be specified. 

SEE ALSO 

pgmhist(l), ppmhist(l), pgm(5), ppm(5) 

AUTHOR 

Wilson H . Bent, Jr. (whb@usc.edu). 

25 October 1993 


pnmindex 

pnmindex— Build a visual index of a bunch of anymaps 


SYNOPSIS 

pnmindex [-size N][-across N][-colors N][-black] pnmfile ... 

DESCRIPTION 

This script makes small versions of a bunch of anymaps, adds labels, and concatenates them together into a collage. 
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OPTIONS 

-size Controls how big each image becomes; the default is 100 x 100 . 

-across Controls how many images are in each row; the default is six. 

-colors Controls how many colors the final index gets quantized to, if quantization isnecessary; the default is256. 

-black Controls the color of the padding between the images; normally it's white and the labels are black lettering on 
white background, but the -black flag reverses this 

SEE ALSO 

pnmscale(l), pnmcat(l), pbmtext(l), ppmquant(l), pnm(5) 

BUGS 

It's very slow. 

It'sa csh script, csh scripts are not portable to System V. Scriptsin general are not portableto non-UN IX environments. 

AUTHOR 

Copyright © 1991 byJef Poskanzer. 

9 January 1991 


pnminvert 

pnminvert — I nvert a portable anymap 

SYNOPSIS 

pnminvert [pnmfiI e ] 

DESCRIPTION 

pnminvert reads a portable anymap as input, inverts it black for white, and produces a portable anymap as output. 

SEE ALSO 

pnm(5) 

AUTHOR 

Copyright © 1989 by J ef Poskanzer. 

8 August 1989 


pnmmargin 

pnmmargin — Add a border to a portable anymap 

SYNOPSIS 

pnmmargin [-white \ -black]-color col orspec ] size [pnmfile] 

DESCRIPTION 

pnmmargin reads a portable anymap as input, adds a border of the specified number of pixels, and produces a portable anymap 
as output. 
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OPTIONS 

You can specify the border color with the -white, -black, and -color flags If no color isspecified, the program makesa 
guess. 


SEE ALSO 

pnm(5) 

BUGS 

It'sascript. Scripts are not portable to non-UN IX environments 

AUTHOR 

Copyright © 1991 byJef Poskanzer. 

9 January 1991 


pnmnlfilt 

pnmnifiit— N onlinear filters: smooth, alphatrim mean, optimal estimation smoothing, edge enhancement. 

SYNOPSIS 

pnmnlfilt alpha radius [pnmfile] 

DESCRIPTION 

This is something of a Swiss army knife filter. It has three distinct operating modes In all of the modes each pixel in the 
image is examined and processed according to it and its surrounding pixels values Rather than using the nine pixels in a3x3 
block, seven hexagonal area samples are taken, the size of the hexagons being controlled by the radius parameter. A radius 
value of 0.3333 meansthat the seven hexagons exactly fit into the center pixel (that is there will be no filtering effect). A 
radius value of i .0 meansthat the se/en hexagons exactly fit a 3 x 3 pixel array. 

ALPHA-TRIMMED MEAN FILTER (0.0 < = alpha < = 0.5) 

The value of the center pixel will be replaced by the mean of the seven hexagon values, but the seven values are sorted by size 
and the top and bottom alpha portion of the seven are excluded from the mean. This implies that an alpha value of 0.0 gives 
the same sort of output as a normal convolution (that is, averaging or smoothing filter), where radius will determine the 
"strength" of the fi Iter. A good value to start from for subtle filtering isaipha = 0 . 0 , radius = 0 . 55 . For a more blatant effect, 
try alpha = 0.0 and radius = 1 . 0 . 

An alpha value of 0.5 will cause the median value of the seven hexagons to be used to replace the center pixel value. This sort 
of filter is good for eliminating "pop" or single pixel noise from an image without spreading the noise out or smudging 
features on the image. J udicious use of the radius parameter will fine-tune the filtering. I ntermediate values of alpha give 
effects somewhere between smoothing and "pop" noise reduction. For subtle filtering, try starting with valuesof alpha = 0 . 4 , 
radius = 0 . 6 . For a more blatant effect, try alpha = 0 . 5 , radius = 1 . 0 . 

OPTIMAL ESTIMATION SMOOTHING. (1.0 < = alpha < = 2.0) 

This type of filter applies a smoothing filter adaptively over the image. For each pixel, the variance of thesu mounding 
hexagon values is calculated, and the amount of smoothing is made inversely proportional to it. The idea is that if the 
variance issmall, then it isdueto noise in the image while if the variance is large it is because of "wanted" image features 
As usual, the radius parameter controls the effective radius but it probably advisable to leave the radius between 0.8 and 1.0 
for the variance calculation to be meaningful. The alpha parameter sets the noise threshold, over which less smoothing will 
be done This meansthat small valuesof alpha will give the most subtle filtering effect, while large values will tend to smooth 
all parts of the image. You could start with values like alpha = 1 . 2 , radius = i.oand try increasing or decreasing theaipha 
parameter to get the desired effect. This type of filter is best for filtering out dithering noise in both bitmap and color images 
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EDGE ENHANCEMENT. (-0.1 > = alpha > = -0.9) 

T his is the opposite type of filter to the smoothing filter. It enhances edges. The alpha parameter controls the amount of 
edge enhancement, from subtle (-0.1) to blatant (-0.9). The radius parameter controls the effective radius as usual, but 
useful valuesare between 0.5 and 0.9. Try starting with valuesof alpha = 0.3, radius = 0.8. 

COMBINATION USE 

T he various modes of pnmnif lit can be used one after the other to get the desired result. Forinstanceto turn a monochrome 
dithered image into a grayscale image, you could try one or two passes of the smoothing filter, followed by a pass of the 
optimal estimation filter, then some subtle edge enhancement. N otethat using edge enhancement isonly likely to be useful 
after one of the nonlinear filters (alpha-trimmed mean or optimal estimation filter), as edge enhancement isthe direct 
opposite of smoothing. 

For reducing color quantization noise in images (that is, turning GIF files back into 24-bit files), you could try a pass of the 
optimal estimation filter (alpha 1.2, radius 1.0), a pass of the median filter (alpha 0.5, radius 0.55), and possibly a pass of 
the edge enhancement filter. Several passes of the optimal estimation filter with declining alpha values are more effective than 
a single pass with a large alpha value. As usual, there is a tradeoff between filtering effectiveness and loosing detail. Experi¬ 
mentation isencouraged. 

REFERENCES 

Thealpha-trimmed mean filter is based on the description in IEEE CG&A, M ay 1990, page 23, by Mark E. Lee and Richard 
A. Redner, and has been enhanced to allow continuous alpha adjustment. 

The optimal estimation filter is taken from an article "Converting Dithered I mages Back to Grayscale" by Allen Stenger, Dr. 
Dobb'sjournal, November 1992, and thisartide references "Digital Image Enhancement and Noise Filtering by Use of Local 
Statistics" by Jong-Sen Lee, IEEE T ransadionson Pattern Analyasand M achine Intelligence, M arch 1980. 

The edge enhancement details are from pgmenhance(l), which is taken from Philip R. Thornpson'sxim program, which in 
turn took it from Section 6 of "D igital FI alftones by Dot Diffusion" by D. E. Knuth, ACM Transaction on Graphics Vol. 6, 

N 0.4, October 1987, which in turn got it from two 1976 papersby J. F. Jarviset al. 

SEE ALSO 

pgmenhance(l), pnmconvol(l), pnm( 5 ) 


BUGS 

Integers and tables may overflow if ppm_maxmaxval is greater than 255 . 

AUTHOR 

G raeme W . G ill (graeme@labtam.oz.au). 

5 February 1993 


pnmnoraw 

pnmnoraw— Force a portable anymap into plain format 

SYNOPSIS 

pnmnoraw [pnmfi I e] 

DESCRIPTION 

pnmnoraw reads a portable anymap as input and writes it out in plain (nonraw) format. Thisisfairly useless if you haven't 
defined the pbmplus_rawbits compile-time option. 
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SEE ALSO 

pnm( 5 ) 

AUTHOR 

Copyright © 1991 byJef Poskanzer. 


8 January 1991 


pnmpad 

pnmpad— Add borders to portable any map 

SYNOPSIS 

pnmpad [-white|-black] [-1#] [-r#] [-t#] [-b#] [pnmfile] 

DESCRIPTION 

pnmpad reads a portable anymap as input and outputsa portable anymap with extra borders of the sizes specified. The color of 
the borders can be set to black or white (default black). 

SEE ALSO 

pbmmake(l), pnmpaste(l), pbm( 5 ) 

AUTHOR 

Copyright© 1990 by Angus Duggan. Copyright© 1989 by Jef Poskanzer. 

pnmpaste 

pnmpaste— Paste a rectangle into a portable anymap 

SYNOPSIS 

pnmpaste [-replace! -or | -and J -xor] f r ompnmf i I e x y [i ntopnmfi I e] 

DESCRIPTION 

pnmpaste reads two portable anymaps as input, inserts the first anymap into the second at the specified location, and produces 
a portable anymap the same size as the second asoutput. If the second anymap is not specified, it is read from stdin. Thex 
and y can be negative in which case they are interpreted relative to the right and bottom of the anymap, respectively. 

This tool is most useful in combination with pnmcut. For instance, if you want to edit a small segment of a large image and 
your image editor cannot edit the large image you can cut out the segment you are interested in, edit it, and then paste it 
back in. 

Another useful companion tool is pbmmask. 

The optional flag specifies the operation to use when doing the paste The default is -replace. The other logical operations 
are only allowed if both input images are bitmaps. These operations act as if white isTRUE and black is false. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pnmcut(l), pnminvert(l), pnmarith(l), pnm( 5 ), pbmmask(l) 
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AUTHOR 

Copyright © 1989,1991 byJef Poskanzer. 


21 February 1991 


pnmrotate 

pnmrotate — Rotate a portable anymap by some angle 

SYNOPSIS 

pnmrotate [-noantialias] angle [pnmfile] 

DESCRIPTION 

pnmrotate reads a portable anymap as input, rotates it by the specified angle, and produces a portable anymap as output. If 
the input file is in color, the output will be, too; otherwise it will be grayscale. The angle is in degrees (floating-point), 
measured counter-clockwise. It can be negative but it should be between -90 and 90. Also, for rotations greater than 45 
degrees you may get better results if you first use pnmfiip to do a 90-degree rotation and then pnmrotate less than 45 degrees 
back the other direction. 

The rotation algorithm is Alan Paeth's three-shear method. Each shear is implemented by looping over the source pixels and 
distributing fractions to each of the destination pixels. This has an antialiasing effect— it avoidsjagged edges and similar 
artifacts H owever, it also means that the original colorsorgray levels in the image are modified. If you need to keep 
precisely the same set of colors you can use the -noantiaiias flag. This does the shearing by moving pixels without changing 
their values If you want antialiasing and don't care about the precisecolors, but still need a limited ‘number* of colors you 
can run the result through ppmquant. 

All flags can be abbreviated to their shortest unique prefix. 

REFERENCES 

"A Fast Algorithm for General Raster Rotation" by Alan Paeth, Graphics Interface '86, pages 77-81. 

SEE ALSO 

pnmshear(l), pnmflip(l), pnm( 5 ), ppmquant(l) 

AUTHOR 

Copyright © 1989,1991 by J ef Poskanzer. 

12 January 1991 


pnmscale 

pnmscale- Scale a portable anymap 

SYNOPSIS 

pnmscale s [pnmf i I e ] 

pnmscale -xsize]-width|-ysize| -heights [pnmfile] 
pnmscale -xscale]-yscale s [pnmfile] 

pnmscale -xscalej-xsize]-width s -yscale]-ysize]-height s [pnmfile] 
pnmscale -xysize x y [pnmfile] 
pnmscale -pixels n [pnmfile] 
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DESCRIPTION 

pnmscaie reads a portable anymap as input, scales it by the specified factor or factors, and produces a portable anymap as 
output. If the input file is in color, the output will be too; otherwise, it will be grayscale. You can both enlarge (scale factor > 
1) and reduce (scale factor < 1). 

You can specify one dimension asa pixel size, and the other dimension will be scaled correspondingly. 

You can specify one dimension as a scale and the other dimension will not be scaled. 

You can specify different sizes or scales for each axis. 

You can usethespecial -xysize flag, which fitsthe image into the specified size without changing the aspect ratio. 

0 r, you can use the -pixels flag, which fits the image into the specified number of pixels without changing the aspect ratio. 
All flags can be abbreviated to their shortest unique prefix. 

If you enlarge by a factor of three or more you should probably add a pnmsmooth step; otherwise you can see the original 
pixels in the resulting image. 

SEE ALSO 

pbmreduce(l), pnmenlarge(l), pnmsmooth(l), pnm(5) 

AUTHOR 

Copyright © 1989,1991 byJef Poskanzer. 

12 January 1991 



pnmshear 

pnmsheai — Shear a portable anymap by some angle 

SYNOPSIS 

pnmshear [-noantialias] angle [pnmfile] 

DESCRIPTION 

pnmshear reads a portable anymap as input, shears it by the specified angle, and produces a portable anymap as output. If the 
input file is in color, the output will be too; otherwise, it will be grayscale. The angle is in degrees (floating-point), and 
measures this 


| OLD]]\NEW \ 

+-+ |gle+-+ 

If the angle is negative it shears the other way: 

lllgi//' 

| OLD !! el NEW / 



The angle should not get too close to 90 or-90, or the resulting anymap will be unreasonably wide 
The shearing is implemented by looping over the source pixels and distributing fractions to each of the destination pixels 
This has an antialiasing effect-it avoids jagged edges and similar artifacts However, it also means that the original colorsor 
gray levels in the image are modified. If you need to keep precisely the same set of colors you can usethe-noantiaiias flag. 
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This does the shearing by moving pixels without changing tha'r values If you want antialiasing and don't care about the 
precise colors but still need a limited "number* of colors, you can run the result through ppmquant. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pnmrotate(l), pnmflip(l), pnm(5), ppmquant(l) 

AUTHOR 

Copyright © 1989,1991 byJef Poskanzer. 

12 January 1991 


pnmsmooth 

pnmsmooth— Smooth out an image 

SYNOPSIS 

pnmsmooth [pnmf i Ie] 

DESCRIPTION 

pnmsmooth smoothsout an image by replacing each pixel with the average of its nine immediate neighbors. It is implemented 
as a simple script using pnmconvoi. 

SEE ALSO 

pnmconvol(l), pnm(5) 

BUGS 

It'sascript. Scripts are not portable to non-UN IX environments 

AUTHOR 

Copyright © 1989,1991 byjef Poskanzer 

13 January 1991 


pnmtile 

pnmtiie— Replicate a portable anymap into a specified size 

SYNOPSIS 

pnmtile width height [pnmfile] 

DESCRIPTION 

pnmtiie reads a portable anymap as input, replicates it until it isthe specified size, and produces a portable anymap asoutput. 

SEE ALSO 

pnm(5) 

AUTHOR 

Copyright © 1989 by J ef Poskanzer. 


13 May 1989 
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pnmtoddif 

pnmtoddif — C on vert a portable anymap to D DIF format 

SYNTAX 

pnmtoddif pnmtoddif [-resolution x y] [pnmfile [ddiffile]] 

OPTIONS 

resolution x y The horizontal and vertical resolution of the output imagein dots per inch. Defaultsto 78dpi. 
pnmf i i e The filename for the image file in PN M format. If this argument is omitted, input is read from stdin. 

ddiffile The filename for the image file to be created in DD IF format. If this argument is omitted, theddi f f i i e is 

written to standard output. It can only specified if a pnmf i i e is also specified. 

DESCRIPTION 

pnmtoddif takes a portable anymap from standard input and converts it into a DD IF image file on standard output or the 
specified D D IF file. 

PBM format (bitmap) data is written as 1-bit D DIF, PGM format data (grayscale) as 8-bit grayscale D DIF, and PPM format 
data is written as 8,8,8-bit color DDIF.AII DDIF image files are written as uncompressed. The data plane organization is 
interleaved by pixel. 

In addition to the number of pixels in the width and height dimension, DDIF images also carry information about the size 
that the image should have, that is, the physical space that a pixel occupies PBM PLUS images do not carry this information, 
hence it has to be externally supplied. T he default of 78dpi has the beneficial property of not causing a resize on most D igital 
Equipment Corporation color monitors 

AUTHOR 

Burkhard Neidecker-Lutz 

Digital Equipment Corporation, CEC Karlsruhe 

neideck@nestvx.enet.dec.com 

pnmtofits 

pnmtof its— Convert a portable anymap into FITS format 

SYNOPSIS 

pnmtofits [-max f ][-min f ] [pnmf i I e ] 

DESCRIPTION 

pnmtofits reads a portable anymap as input and produces a FITS (Flexible I mage Transport System) file as output. The 
resolution of the output file is either 8 bits/pixel, or 16 bit^pixel, depending on the value of maxvai in the input file If the 
input file is a portable bitmap or a portable graymap, theoutputfileconsistsofasingleplaneimage(NAxis = 2 ). If instead 
the input file is a portable pixmap, the output file will consist of a three-plane image (naxis = 3 , naxis3 = 3 ). A full 
description of the FITS format can be found in Astronomy& Astrophys'csSupplement Series44 (1981), page 363. 

OPTIONS 

Flags -min and -max can be used to set datamax, datamin, bscale, and bzero in the FITS header, but do not cause the data to 
be rescaled. 

SEE ALSO 

fitstopnm(l), pgm(5) 
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AUTHOR 

Copyright © 1989 by Wilson H. Bent (whb@hoh-2.att.com), with modifications by Alberto Accomazzi 
(alberto@cfa.harvard.edu). 

5 December 1992 


pnmtops 

pnmtops- Convert portable anymap to PostScript 

SYNOPSIS 

pnmtops [-scale s][-turn]-noturn][-rle|-runlength][-dpi n][-width n][- height n] 

[-center!-nocenter][pnmfi I e] 

DESCRIPTION 

pnmtops reads a portable anymap asinput and produces encapsulated PostScript as output. 

If the input file is in color (PPM), a color PostScript file gets written. Some PostScript interpreters can't handle color 
PostScript. If you have one of these, you will need to run your image through ppmtopgm first. 

N otethat there is no pstopnm tool; thistransformation isone-way, because a pstopnm tool would be a full-fledged PostScript 
interpreter, which is beyond the scope of this package. H owever, see the psidtopgm tool, which can read grayscale non-run- 
length PostScript image data. Also, if you're willing to install the fairly I arge G hostScript package, it comes with apstoppm 
script. 

OPTIONS 

The -scale flag controls the scale of the result. Thedefault scale isi, which on a 300dpi printer such asthe Apple 
LaserWriter makes the output look about the same size as the input would if it wasdisplayed on atypical 72dpi screen. T 0 
get onePN M pixel per 300dpi printer pixel, use -scale 0.25. 

The-turn and -noturn flags control whether the image gets turned 90 degrees. Normally, if an image is wider than itistall, 
it gets turned automatically to better fit the page. If the -turn flag isspecified, it will be turned no matter what its shape; and 
if the -noturn flag isspecified, it will not be turned no matter what its shape 

The -rie or -runlength flag specifies run-length compression. This may save time if the host-to-printer link is slow; but 
normally the printer's processing time dominates, so -ne makes things slower. 

The - dpt flag lets you specify the dots per inch of your output device Thedefault is 300dpi. In theory PostScript is device¬ 
independent and you don't have to worry about this, but in practice its raster rendering can have unsightly bands if the 
device pixels and the image pixels aren't in sync. 

The -width and -height flags let you specify the size of the page. Thedefault is 8.5 inches by 11 inches. 

With the -nocenter flag, the output is not centered on the page; it appears in the upper-left corner. This is useful for 
programs that can include PostScript files, but can't cope with pictures that are not positioned in the upper-left corner. The 
default is -center--the image is centered on the page 
All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pnm( 5 ), psidtopgm(l) 

AUTHOR 

Copyright© 1989,1991 byjefPoskanzer. M odified N ovember 1993 by Wolfgang Stuerzlinger (wrzi@gup.uni-iinz.ac.at,). 

26 October 1991 
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pnmtorast 

pnmtorast— Convert a portable pixmap into a Sun raster file 

SYNOPSIS 

pnmtorast [-standard!-rle][pnmf i I e] 

DESCRIPTION 

pnmtorast reads a portable pixmap as input and produces a Sun raster file as output. 

Color values in Sun raster files are eight bits wide, so pnmtorast will automatically scale colors to have a maxvai of 255. An 
extra pnmdepth step is not necessary. 

OPTIONS 

The -standard flag forces the result to be in rt_standard form; the -ne flag, rt_byte_encoded, which issmaller but, well, less 
standard. The default is -ne. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

rasttopnm(l), pnm( 5 ) 

AUTHOR 

Copyright © 1989,1991 byJef Poskanzer. 

12 January 1991 


pnmtosgi 

pnmtosgi— Convert a portable anymap to an SGI image file 

SYNOPSIS 

pnmtosgi [-verbatim!-rle][-imagename Name][pnmfile] 

DESCRIPTION 

pnmtosgi reads a portable anymap as input and producesan SGI image file asoutput. The SGI image will be two-dimen¬ 
sional (onechannel) for PBM and PGM input, and three-dimensional (threechannels) for PPM . 

OPTIONS 

-verbatim W rite an uncompressed file 

-ne (default) W rite a compressed (run-length-encoded) file. 

-imagename name Write the string name into the imagename field of the header. The name string is limited to 79 characters. If 
no name is given, pnmtosgi writes no name into thisfield. 

BUGS 

Probably. 

REFERENCES 

SGI image file format documentation (draft v0.95) by Paul H aeberli (paui@sgi.com). Available via FTP at sgi.com:graphics/ 

SGIIMAGESPEC. 
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SEE ALSO 

pnm(5), sgitopnm(l) 

AUTHOR 

Copyright© 1994 bylngo Wilken (ingo.Wilken&informatik.uni-oldenburg.dej. 

29 January 1994 


pnmtosi r 

pnmtosir— Convert a portable anymap into a Solitaire format 

SYNOPSIS 

pnmtosir [pnmfile] 

DESCRIPTION 

pnmtosir reads a portable anymap as input and produces a Solitaire image recorder format. 

pnmtosir produces an MGI TYPE 17 file for PBM and PGM files For ppm, it writes an MGI TYPE 11 file 

SEE ALSO 

sirtopnm(l), pnm(5) 

AUTHOR 

Copyright © 1991 by M arvin Landis. 

20 March 1991 


pnmtotiff 

pnmtotiff — C on vert a portable anymap i nto a TIF F file 

SYNOPSIS 

pnmtotiff [-none|-packbits! -lzw|-g3]-g4][-2d][-fill][-predictor n] 

[-msb21sb|-lsb2msb] [-rowsperstrip n][pnmf i I e ] 

DESCRIPTION 

pnmtotiff reads a portable anymap as input. ProducesaTIFF file as output. 

OPTIONS 

Bydefault, pnmtotiff createsaTIFF file with LZW compression. Thisis your best bet most of the time. However, some 
TIFF readers can't deal with it. If you want to try another compression scheme or tweak some of the other even more 
obscure output options, there are a number of flags to play with. 

The -none, -packbits, -lzw, -g3,and-g4 options are used to override the default and set the compression schemeused in 
creating theoutput file. TheCCITT Group 3 and Group 4 compression algorithms can only be used with bilevel data. The 
- 2 d and -fill options are meaningful only with Group 3 compression: - 2 d requests two-dimensional encoding, while -fin 
requests that each encoded scanline be zero-filled to a byte boundary. The - predictor option is only meaningful with LZW 
compression: a predictor value of 2 causes each scanline of the output image to undergo horizontal differencing before it is 
encoded; a value of 1 forces each scanline to be encoded without differencing. By default, pnmtotiff createsaTIFF file with 
msb-to-isb fill order. The -msb 2 isb and -isb 2 msb options are used to override the default and set the fill order used in 
creating thefile. The -rowsperstrip option can be used to set the number of rows (scanlines) in each strip of data in the 
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output file. By default, theoutput file hasthe number of rows per strip set to a valuethat will ensure each strip is no more 
than eight kilobytes long. 

BUGS 

This program is not self-contained. To use it you must fetch theTIFF Software package listed in the other.systems file and 
configure pbmplus to useiibtiff. SeePBM -PLUS'S M akefile for details on this configuration. 

SEE ALSO 

tifftopnm(l), pnm(5) 

AUTHOR 

Derived byjef Poskanzerfrom ras 2 tiff.c, which isCopyright© 1990 bySun M icrosystems, Inc. Author: PatrickJ. 

N aughton (naughton@wind.sun.com). 

13 January 1991 


pnmtoxwd 

pnmtoxwd- Convert a portable anymap into an Xll window dump 

SYNOPSIS 

pnmtoxwd [-pseudodepth n][-directcolor][pnmf i I e ] 

DESCRIPTION 

pnmtoxwd reads a portable anymap as input and produces an Xll window dump as output. This window dump can be 
displayed using the xwud tool. 

Normally, pnmtoxwd producesa StaticG ray dump file for PBM and PGM files. For ppm, it writes a Pseudocolor dump file if 
there are up to 256 colors in the input, and a DirectColor dump file otherwise The -directcolor flag can be used to forcea 
DirectColor dump. The - pseudodepth flag can be used to change the depth of Pseudocolor dumps from the default of 8 bits/ 
256 colors. 

SEE ALSO 

xwdtopnm(l), pnm(5), xwud(l) 

AUTHOR 

Copyright© 1989,1991 by J ef Poskanzer. 

24 September 1991 


ppm3d 

ppm3d- Convert two portable pixmap into a red/blue 3D glasses pixmap 

SYNOPSIS 

ppm3d leftppmfile ri ghtppmfi I e [hor i zont al _of f set ] 

DESCRIPTION 

ppm3d reads two portable pixmaps as input and producesa portable pixmap as output, with the images overlapping by 

horizontai_offset pixels in blue/red format. 

horizontai_offset defaults to 30 pixels. Pixmapsmust bethesamesize. 



ppmchange 




SEE ALSO 

ppm(5) 

AUTHOR 

Copyright © 1993 by David K. Drum. 


2 N ovember 1993 


ppmbrighten 

ppmbrighten- Change an image's saturation and value from an HSV map 

SYNOPSIS 

ppmbrighten [-n] [-s <+- saturation^ [-v <+■ value>] <ppmfile> 

DESCRIPTION 

ppmbrighten reads a portable pixmap as input, converts the image from RGB space to H SV space, and changes the value by 
<+■ vaiue> as a percentage; thesamewith the saturation. Use 

ppmbrighten -v 100 

to add 100 percent to the value 

Thenoption normalizes the value to exist between Oand 1 (normalized). 

SEE ALSO 

pgmnorm(l), ppm(5) 

AUTHOR 

Copyright© 1990 by Brian M offet. Copyright© 1989 byjef Poskanzer. 

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is 
hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this 
permission notice appear in supporting documentation. This software isprovided "as is" without expressor implied 
warranty. 

NOTES 

This program does not change the number of colors. 

20 N ovember 1990 


ppmchange 

ppmchange- Change all pixels of one color to another in a portable pixmap 

SYNOPSIS 

ppmchange ol dcol or newcolor [...] [ppmfile] 

DESCRIPTION 

ppmchange reads a portable pixmap as input and changes all pixels of oi dc oi or to newco or, leaving all others unchanged. Up 
to 256 colors may be replaced by specifying couples of colors on the command line 
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Thecolorscan be specified in five ways: 

■ A name, assuming that a pointer to an X 11-style color names file wascompiled in. 

■ An X 11-style hexadecimal specifier: rgb: r/g/b, where r, g, and b are each 1- to 4-digit hexadecimal numbers. 

■ An X 11-style decimal specifier: rgbi: r/g/b, where r, g, and b are floating-point numbers between 0 and 1. 

■ For backwards compatibility, an old-Xll-style hexadecimal number: #rgb, #rrggbb, #rmgggbbb, or#rmrggggbbbb. 

■ For backwards compatibility, a triplet of numbers separated by commas: r,g,b, where r, g, and b are floating-point 
numbers between 0 and 1. (This style was added before M IT came up with the similar rgbi style) 

SEE ALSO 

pgmtoppm(l), ppm(5) 

AUTHOR 

Wilson FI. Bent, Jr. (whb@usc.edu), with modifications by Alberto Accomazzi (aiberto@cfa.hanvard.edu). 

3 December 1993 


ppmdim 

ppmdim— Dima portable pixmap down to total blackness 

SYNOPSIS 

ppiudim di mf act or [ppmf i I e ] 

DESCRIPTION 

ppmdim reads a portable pixmap as input and diminishes its brightness by the specified dimfactor down to total blackness. T he 
di mf actor may be in the range from 0.0 (total blackness, deep night, nada, null, nothing) to 1.0 (original picture's bright¬ 
ness). 

As pnmgamma does not do the brightness correction in the way I wanted it, I wrote this small program, 
ppmdim is similar to ppmbrighten, but not exactly the same 

SEE ALSO 

ppm(5), ppmflash(l), pnmgamma(l), ppmbrighten(l) 

AUTHOR 

Copyright© 1993 by Frank N eumann. 

16 N ovember 1993 


ppmdist 

ppmdist — Simplistic grayscale assignment for machinegenerated color images 

SYNOPSIS 

ppmdist [-intensity!-frequency][ppmf i I e] 

DESCRIPTION 

ppmdist reads a portable pixmap as input and performs a simplistic grayscale assignment i ntended for use with grayscale or 
bitmap printers. 
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Often conversion from ppm to pgm will yield an image with contrast too low for good printer output. The program maximizes 
contrast between the gray levels' output. 

A ppm input of n colors is read, and a pgm of n gray levels is written. The gray levels take on the values 0 .. .n-i, while maxvai 
takes on n-i. 

The mapping from color to stepped grayscalecan be performed in order of input pixel intensity, or input pixel frequency 
(number of repetitions). 

OPTIONS 

■frequency Sort input colors by the number of times a color appears in the input, before mapping to evenly distrib¬ 
uted gray levels of output. 

-intensity Sort input colors by their grayscale intensity, before mapping to evenly distributed gray levelsof output. 
This is the default. 

BUGS 

Helpful only for images with a very small number of colors. Perhaps should have been an option to ppmtopgm(l). 

SEE ALSO 

ppmtopgm(l), ppmhist(l), ppm(5) 

AUTHOR 

Copyright© 1993 by Dan Stromberg. 

22 July 1992 


ppmdither 

ppmdither— 0 rdered dither for color images 

SYNOPSIS 

ppmdither [-dim di mensi on][- red shades ][-green shades ][-blue shades][ppmf i I e] 

DESCRIPTION 

ppmdither reads a portable pixmap as input, and applies dithering to it to reduce the number of colors used down to the 
specified number ofshadesfor each primary. The default number of shades is red=s, green=9, biue=5, for a total of 225 
colors To convert the image to a binary RGB format suitable for color printers, use -red 2 -green 2 -blue 2. The maximum 
number of colors that can be used is256 andean be computed asthe product of the number of red, green, and blue shades 

OPTIONS 

-dim di mensi on Thesizeof the dithering matrix. M ust be a power of 2. 

■red shades Thenumber of red shades to be used; minimum of 2. 

■green shades Thenumber of green shades to be used; minimum of 2. 

-blue shades Thenumber of blue shades to be used; minimum of 2. 

SEE ALSO 

pnmdepth(l), ppmquant(l), ppm(5) 

AUTHOR 

Copyright© 1991 by C hristos Zoulas. 


14 July 1991 
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ppmflash 

ppmfiash— Brighten a picture up to complete white-out 

SYNOPSIS 

ppmfiash fl ashf act or [ppmf i I e] 

DESCRIPTION 

ppmfiash reads a portable pixmap as input and increases its brightness by the specified f i ashf act or up to a total white-out 
image Then ashf actor may be in the range from 0.0 (original picture's brightness) to 1.0 (full white-out, The Second 
After). 

As pnmgamma does not do the brightness correction in the way I wanted it, I wrote this small program. 

This program issimilarto ppmbrighten, but not exactly the same 

SEE ALSO 

ppm(5), ppmdim(l), pnmgamina(l), ppmbrighten(l) 

AUTHOR 

Copyright© 1993 by Frank l\l eumann. 

16 N ovember 1993 


ppmfonge 

ppmforge — Fractal forgeries of clouds, planets, and starry skies 

SYNOPSIS 

ppmforge [-clouds][-night][-dimension di men ][-hour hour ][-inclination!-tilt angle] 

[-mesh size]]-power factor ][-glaciers level ][-ice level ][-saturation sat ] 

[-seed seed] [-stars fraction]] -xsize]-width wi d th ][-ysize]-height height] 

DESCRIPTION 

ppmforge generates three kindsof "random fractal forgeries," the term coined by Richard F. VossofthelBM Thomas 
J. Watson Research Center for seemingly realistic pictures of natural objects generated by simple algorithmsembodying 
randomness and fractal self-similarity. The techniques used by ppmforge are essentially those given by Voss, particularly the 
technique of spectral synthesis explained in more detail by Dietmar Saupe. (The "See A Iso" subsection provides more 
detailed information about these men's work.) 

The program generates two varieties of pictures, planets and clouds, which are just different renderings of data generated in 
an identical manner, illustrating the unity of the fractal structure of these very different objects. A third type of picture, a 
starry sky, is synthesized directly from pseudorandom numbers. 

The generation of planets or clouds begins with the preparation of an array of random data in the frequency domain. The 
size of this array, the mesh sze, can beset with the -mesh option; the larger the mesh, the more realistic the pictures, but the 
calculation time and memory requirement increases as the square of the mesh size. Thefractal dimension, which you can 
specify with the -dimension option, determines the roughness of the terrain on the planet or the scale of detail in the clouds. 
Asthefractal dimension is increased, more high frequency components are added into therandom mesh. 

After the mesh isgenerated, an inverse two-dimensional Fourier transform is performed upon it. Thisconverts the original 
random frequency domain data into spatial amplitudes You scale the real components that result from the Fourier transform 
into numbers from 0 to 1 associated with each point on the mesh. You can further modify this number by applying apower 
law scale to it with the -power option. Unity scale leaves the numbers unmodified; a power scale of 0.5 takes the square root 
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of the numbers in the mesh, while a power scale of 3 replaces the numbers in the mesh with their cubes. Power law scaling is 
best envisioned by thinking of the data as representing the elevation of terrain; powers less than oneyield landscapes with 
vertical scarps that look like glacial-carved valleys; powers greater than one make fairy-castle spires (which require large mesh 
sizes and high resolution for best results). 

After these calculations, you have an array of the specified size containing numbers that range from 0 to 1. T he pixmaps are 
generated asfollows 

ciouds A color map iscreated that ranges from pure blue to white by increasing admixture (desaturation) of blue with 
white N umbers less than 0.5 are colored blue, and numbers between 0.5 and 1.0 are colored with corresponding 
levels of white, with 1.0 being pure white. 

planet Themesh is projected onto asphere Values less than 0.5 are treated as water and values between 0.5 and 1.0 as 
land. The water areas are colored based on the water depth; land, based on its elevation. The random depth data 
are used to create clouds over the oceans An atmosphere approximately I ike the Earth's is simulated; its light 
absorption iscalculated to create a blue cast around the limb of the planet. A function that rises from 0 to 1 based 
on latitude is modulated by the local elevation to generate polar ice caps- high altitude terrain carries glaciers 
farther from the pole. Based on the position of the star with respect to the observer, the apparent color of each 
pixel of the planet iscalculated by ray-tracing from the star to the planet to the observer and applying a lighting 
model that sums ambient light and diffuse reflection (for most planets ambient light is zero, as their primary star 
is the only source of illumination). Additional random data are used to generate stars around the planet. 

Night A sequence of pseudorandom numbers is used to generate stars with a user-specified density. 

Cloud pictures always contain 256 or fewer colors and may be displayed on most color-mapped devices without further 
processing. Planet pictures often contain tensof thousands of colors that must decompressed with ppmquant or ppmdither 
before encoding in a color-mapped format. If the display resolution is high enough, ppmdither generally produces better¬ 
looking planets, ppmquant tends to create discrete color bands, particularly in the oceans, which are unrealistic and distract¬ 
ing. The number of colors in starry sky pictures generated with the -night option depends on the value specified for 
-saturation. Small values limit the color temperature distribution of thestarsand reduce the number of colors in the image. 

If the -saturation is set to 0, none of the stars will be colored and the resulting image will never contain more than 256 
colors N ight sky pictures with many different star colors often look best when color-compressed by pnmdepth rather than 
ppmquant or ppmdither. T ry newmaxvai settings of 63, 31, or is with pnmdepth to reduce the number of colors in the picture to 
256 or fewer. 

OPTIONS 

-clouds Generate clouds. A pixmap of fractal clouds is generated. Selecting clouds setsthe default 

for fractal dimension to 2.15 and power scale factor to 0 . 75 . 

-dimension di men Sets the fractal dimension to the specified dimen, which may beany floating-point value 

between 0 and 3. H igherfractal dimensionscreatemore"chaotic" images which require 
higher resolution output and a larger FFT mesh sizeto look good. If no dimension is 
specified, 2.4 is used when generating planets and 2.15 for clouds. 

-glaciers level The floating-point i eve i setting controls the extent to which terrain elevation causes iceto 

appear at lower latitudes. The default value of 0.75 makes the polar caps extend toward the 
equator across high terrain and forms glaciers in the highest mountains, as on Earth. FI igher 
values make ice sheets that cover more and more of the land surface, simulating planets in 
the midst of an ice age. Lower values tend to be boring, resulting in unrealistic geometrically 
precise ice cap boundaries 

-hour hour W hen generating a planet, hour is used as the hour angle at the central meridian. If you 

specify -hour 12, for example, the planet will be fully illuminated, corresponding to high 
noon at the longitude at the center of the screen. You can specify any floating-point value 
between 0 and 24 for hour, but values which place most of the planet in darkness (0 to 4 
and 20 to 24) result in crescents which, while pretty, don't give you many illuminated pixels 
for the amount of computing that’s required. If no -hour option is specified, a random hour 
angle is chosen, biased so that only 25 percent of the images generated will be crescents. 
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-ice level Sdtstheextent of the polar icecapsto thegiven floating-point level. Thedefault level of 

0.4 produces ice caps si mi I ar to those of the Earth. Smaller values reduce the amount of ice 
while larger - ice settings create more prominent ice caps. Sufficiently large values, such as 
100 or more, in conjunction with small settings for -glaciers (try 0.1) create "ice balls" like 
Europa. 

-inciination| -tut angle The inclination angle of the planet with regard to its primary star issdt to angle, which can 
be any floating-point value from -90 to 90. The inclination angle can bethought of as 
specifying, in degrees, the "season" the planet is presently experiencing or, more precisely, 
the latitude at which the star transits the zenith at local noon. If 0, the planet is at equinox; 
thestar is directly overhead attheequator. Positive values represent summer in the northern 
hemisphere negative values summer in the southern hemisphere. The Earth's inclination 
angle, for example is about 23.5 at thejune solstice, Oat the equinoxes in M arch and 
September, and -23.5 at the December solstice. If no inclination angle is specified, a 
random value between -21.6 and 21.6 degrees is chosen. 

-mesh size Ameshofsize bysize will be used forthefast Fourier transform (FFT). N otethat 

memory requirements and computation speed increase as the square of s i z e ; if you double 
the mesh size the program will use four times the memory and run four times as long. The 
default mesh is 256x256, which produces reasonably good looking pictures while using half a 
megabyte for the 256x256 array of single precision complex numbers required by the FFT. 

On machines with limited memory capacity, you may have to reduce the mesh size to avoid 
running out of RAM . Increasing the mesh size produces better looking pictures; the 
difference becomes particularly noticeable when generating high-resolution images with 
relatively high fractal dimensions (between 2.2 and 3). 

-night A starry sky is generated. The stars are created by the same algorithm used for the stars that 

surround planet pictures, but the output consists exclusively of stars. 

-power factor Sets the power factor used to scale elevations synthesized from the FFT to f act or , which can 

be any floating-point number greater than zero. If no factor is specified, a default of 1.2 is 
used if a planet is being generated, or 0.75 if clouds are selected by the - clouds option. T he 
result of the FFT image synthesis is an array of elevation values between 0 and 1. A 
nonunity power factor exponentiates each of these elevations to the specified power. For 
example, a power factor of 2 squares each value, while a power factor of 0.5 replaces each 
with its square root. (N otethat exponentiating values between 0 and 1 yields values that 
remain within that range.) Power factors less than 1 emphasize large-scale elevation changes 
at the expense of small variations Power factors greater than 1 increase the roughness of the 
terrain and, like high fractal dimensions may require a larger FFT mesh size or higher 
screen resolution to look good. 

- saturation sat C ontrols the degree of color saturation of the stars that surround planet pictures and fill 

starry skies created with the -night option. Thedefault value of 125 creates stars that 
resemble the sky as seen by the human eye from Earth's surface Stars are dim; only the 
brightest activate the cones in the human retina, causing color to be perceived. H igher 
values of sat approximate the appearance of stars from Earth orbit, where better dark 
adaptation, absence of sky glow, and the concentration of light from a given star onto a 
smaller area of the retina thanks to the lack of atmospheric turbulence enhances the 
perception of color. Values greater than 250 create "sciencefiction" skies that, while pretty, 
don't occur in this universe 

Thanks to the inverse square law combined with nature's love of mediocrity, there are 
many, many dim stars for every bright one. This population relationship is accurately 
reflected in the skies created by ppmforge. Dim, low mass stars live much longer than bright, 
massive stars; consequently there are many reddish stars for every blue giant. This relation¬ 
ship is preserved by ppmforge. You can reverse the proportion, simulating the sky as seen in a 
starburst galaxy, by specifying a negative sat value. 



ppm forge 




-ysize]-height height 


Sdts the seed for the random number generator to the integer num. The seed used to create 
each picture is displayed on standard output (unless suppressed with the -quiet option). 
Pictures generated with the same seed will be identical. If no -seed is specified, a random 
seed derived from the date and time will be chosen. Specifying an explicit seed allows you to 
re-render a picture you particularly like at a higher resolution or with different viewing 
parameters 

Specifies the percentage of pixels in tenths of a percent, that will appear as stars either 
surrounding a planet or filling the entire frame if -night is specified. T he default fraction is 
100. 

Sdts the width of the generated image to wi dth pixels. The default width is256 pixels 
I mages must be at least as wide as they are high; if a width less than the height is specified, it 
will be increased to equal the height. If you must have a long, skinny pixmap, make a square 
one with ppmtorge, then use pnmcut to extract a portion of the shape and size you require. 
Sdts the height of the generated image to hei ght pixels Thedefault height is256 pixels If 
the height specified exceeds the width, the width will beincreased to equal the height. 


All flags can be abbreviated to their shortest unique prefix. 


BUGS 

T he algorithms require the output pixmap to be at least as wide as it is high, and the width to be an even number of pixels 
These constraints are enforced by increasing the size of the requested pixmap if necessary. 

You may have to reduce the FFT mesh size on machines with 16-bit integers and segmented pointer architectures 

SEE ALSO 

pnmcut(l), pnmdepth(l), ppmdither(l), ppmquant(l), ppm( 5 ) 

"Random Fractal Forgeries" by Richard F. Voss, in Fundamental Algorithmsfor Computer Graphics by Earnshaw et al. Berlin: 
Springer-V erlag, 1985. 

TheScienceOfFractal Images, edited by H. 0. Peitgen and D. Saupe. New York: Springer-Verlag, 1988. 

AUTHOR 

John Walker 
Autodesk SA 

Avenue desChampsM ontantsl4b 
CH-2074 MARIN 

Suiss^Schweiz/Svi zzera/ Svizra/ Swi tzerl an d 
Usenet: kelvin@Autodesk.com 

Fax: 038/33 88 15 

Voice: 038/33 76 33 


Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is 
hereby granted, without any conditions or restrictions. T hissoftware is provided "as is" without express or implied warranty. 
PLUG WARE! If you like this kind of stuff, you may also enjoy J ames G leick’s "Chaos- The Software" for M S-DOS, 
availablefor $59.95 from your local software store or directly from Autodesk, Inc., Attn: Science Series, 2320 M arinship 
Way, Sausalito, CA 94965, USA. Telephone: 800-688-2344 toll-free or, outside the U.S. 415-332-2344 Ext 4886. 

F ax: 415-289-4718. "C haos— T he Software! 1 includes a more comprehensive fractal forgery generator that creates three- 
dimensional landscapes as well as clouds and planets, plus five more modules that explore other aspects of Chaos. The user 
guide of more than 200 pages includes an introduction byJamesGleick and detailed explanations by Rudy Rucker of the 
mathematics and algorithms used by each program. 


25 October 1991 
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ppmhist 

ppmhist— Print a histogram of a portable pixmap 

SYNOPSIS 

ppmhist [ppmf i I e ] 

DESCRIPTION 

ppmhist reads a portable pixmap as input and generates a histogram of the colors in the pixmap. 

SEE ALSO 

ppm( 5 ), pgmhist(l) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

3 April 1989 


ppmmake 

ppmmake— C reate a pixmap of a specified size and color 

SYNOPSIS 

ppmmake col or wi dt h hci ght 

DESCRIPTION 

ppmmake produces a portable pixmap of the specified color, width, and height. 

The color can be specified in five ways; 

■ A name, assuming that a pointer to an X 11-style color names file wascompiled in. 

■ An X 11-style hexadecimal specifier: rgb: r/g/b, where r, g, and b are each 1- to 4-digit hexadecimal numbers. 

■ An X 11-style decimal specifier: rgbt: r/g/b, where r, g, and b are floating-point numbers between 0 and 1. 

■ For backwards Compatibility, an Old-Xll-Style hexadecimal number: #rgb, #rrggbb, #rrrgggbbb, Or#rrrrggggbbbb. 

■ For backwards compatibility, a triplet of numbers separated by commas r,g,b, where r, g, and b are floating-point 
numbers between 0 and 1. (Thisstyle was added before M IT came up with thesimilar rgbi style) 

SEE ALSO 

ppm( 5 ), pbmmake(l) 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

24 September 1991 


ppmmix 

ppmmix— Blend together two portable pixmaps 

SYNOPSIS 


ppmmix fadef 


ppmf i I el ppmf i I e2 



ppmntsc 
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DESCRIPTION 

ppmmix reads two portable pixmaps as input and mixes them together using the specified fade factor. The fade factor may be 
in the range from 0.0 (only ppmf i i ei 'si mage data) to 1.0 (only ppmf i i e 2 's image data). Anything in between gainsa smooth 
blend between thetwo images. 

Thetwo pixmaps must havethesamesize 

SEE ALSO 

ppm(5) 

AUTHOR 

Copyright© 1993 by Frank N eumann. 

16 N member 1993 


ppmnorm 

ppmnorm— N ormalizethecontrast in a portable pixmap 

SYNOPSIS 

ppmnorm[-bpercent N | -bvalue N][-wpercent N ] -wvalue N][ pp mf i I e] 

DESCRIPTION 

ppmnorm reads a portable pixmap as input; normalizes the contrast by forcing the lightest pixels to white the darkest pixels to 
black, and linearly rescaling the ones in between; and produces a portable pixmap as output. 

It works by computing the relative gray level of each pixel as with ppmtopgm, and uses those values to scale the RGB levels. 
Note that this isdifferent from using pgmnorm on the individual red,green, and bluegraymaps (as produced by ppmtorgb3) 
and recombining them. 

OPTIONS 

By default, the darkest two percent of all pixels are mapped to black, and the lightest one percent are mapped to white. You 
can override these percentages by using the -bpercent and -^percent flags, or you can specify the exact pixel values to be 
mapped by using the -bvaiue and -wvaiue flags. Appropriate numbers for theflags can begotten from theppmhist tool. If 
you just want to enhance the contrast, then choose values at elbows in the histogram; for example if value 29 represents 3 
percent of the image but value 30 represents 20 percent, choose30 for bvaiue. If you want to lighten the image, then set 
bvaiue to 0 and just fiddle with wvaiue; similarly, to darken the image set wvaiue to maxvai and play with bvaiue. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pgmnorm(l), ppmhist(l), ppm(5) 

AUTHOR 

Wilson H . Bent, Jr. (whb@usc.edu), heavily based on the pgmnorm filter by Jef Poskanzer. 

7 October 1993 


ppmntsc 

ppmntsc- M ake a portable pixmap look like it is taken from an American TV show 

SYNOPSIS 

ppmntsc di mf act or [ppmf i I e ] 
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DESCRIPTION 

ppmntsc reads a portable pixmap as input and dims every other row of image data down by the specified dim factor. This 
factor may be in the range of 0.0 (the alternate lines are totally black) to 1.0 (original image). 

This creates an effect similar to what I saw once in the video clip "You Could beM ine" by Guns'n' Roses. In the scene I'm 
talking about you can seejohn Connor on his motorbike, looking up from the water trench (?) he's standing in. While the 
camera pulls back, the image becomes "normal" by brightening up the alternate rows of it. I thought this would bean 
interesting effect to try in M PEG. I did not yet check this out, however. T ry for yourself. 

SEE ALSO 

PPm( 5 ), ppmdim(l) 

AUTHOR 

Copyright© 1993 by Frank N eumann. 

16 N ovember 1993 


ppmpat 

ppmpat— M ake a pretty pixmap 

SYNOPSIS 

ppmpat -gingham 2 ]-g 2 |-gingham 3 | -g 3 |-madras!-tartan] -poles|-squig]-camo| 

-anticamo width height 

DESCRIPTION 

ppmpat produces a portable pixmap of the specified width and height, with a pattern in it. 

This program is mainly to demonstrate use of the ppmdraw routines, a simple but powerful drawing library. See the ppmdraw. h 
includefilefor more information on using these routines. Still, some of the patterns can be rather pretty. If you have a color 
workstation, something like ppmpat -squig 300 300 | ''ppmquant 128" should generatea nice background. 

OPTIONS 

The different fl ags specify various different pattern types: 

-gingham2 A gingham check pattern. Can betiled. 

-gingham 3 A slightly more complicated gingham. Can betiled. 

-madras A madrasplaid. Can betiled. 

-tartan A tartan plaid. Can betiled. 

-poles Color gradients centered on randomly placed poles M ay need to be run through ppmquant. 

-squig Squiggly tubular pattern. Can betiled. M ay need to be run through ppmquant. 

-camo Camouflage pattern. M ay need to be run through ppmquant. 

-anticamo Anticamouflage pattern; like -camo, but ultra-bright colors M ay need to be run through ppmquant. 

All flags can be abbreviated to their shortest unique prefix. 

REFERENCES 

Some of the patterns are from "Designer's Guide to Color 3" byJeanneAllen. 

SEE ALSO 

pnmtile(l), ppmquant(l), ppm( 5 ) 




ppmquant 




AUTHOR 

Copyright© 1989 byjef Poskanzer. 


4 September 1989 


ppmquant 

ppmquant— Q uantizethecolorsin a portable pixmap down to a specified number 

SYNOPSIS 

ppmquant [-floyd|-fs] ncolors [ppmfile] 
ppmquant [-floyd |-fs] -map ma pf i I e [ppmfile] 

DESCRIPTION 

ppmquant reads a portable pixmap as input. It chooses ncoiors colors to best represent the image, maps the existing colors to 
the new ones, and writes a portable pixmap as output. 

The quantization method is Heckbert's "median cut." 

Alternately, you can skip the color-choosing step by specifying your own set of colors with the-map flag. The mapf lie is just 
a ppm file; it can be any shape all that matters is the colors in it. For instance, to quantize down to the 8-color IBM TTL 
color set, you might use the following: 

P3 

255 
0 0 0 
255 0 0 
0 255 0 
0 0 255 
255 255 0 
255 0 255 
0 255 255 
255 255 255 

If you want to quantize one pixmap to use the colors in another one, just use the second one as the mapfile You don't have 
to reduce it down to only one pixel of each color, just use it as is 

The -floyd/-fs flag enables a Floyd-Steinberg error diffusion step. Floyd-Stein berg gives vastly better results on images 
where the unmodified quantization has banding or other artifacts especially when going to asmall number of colors such as 
the preceding IBM set. Flowever, it does take substantially more CPU time, so the default isoff. 

All flags can be abbreviated to their shortest unique prefix. 

REFERENCES 

"Color I mageQ uantization for Frame Buffer D isplay," by Paul FI eckbert, siggraph '82 Proceedings, page 297. 

SEE ALSO 

ppmquantall(l), pnmdepth(l), ppmdither(l), ppm( 5 ) 

AUTHOR 

Copyright© 1989,1991 by J ef Poskanzer. 


12 January 1991 
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ppmquantaii— Run ppmquant on a bunch of files all at once, so they share a common colormap 

SYNOPSIS 

ppmquantall ncol or s ppmf i I e ... 

DESCRIPTION 

ppmquantaii takesa bunch of portable pixmap as input. It chooses ncoi or s colorsto best represent all of the images, mapsthe 
existing colors to the new ones, and overwrites the input files with the new quantized versions 

Verbose explanation: Say you haveadozen pixmaps that you want to display on the screen all atthesametime Your screen 
can only display 256 different colors but the pixmaps have a total of a thousand or so different colors Fora single pixmap, 
you solve this problem with ppmquant; this script solves it for multiple pixmaps All it does is concatenate them together into 
one big pixmap, run ppmquant on that, and then split it up into little pixmaps again. 

(N otethat another way to solve this problem is to preselect a sdt of colors and then useppmquant's -map option to separately 
quantize each pixmap to that set.) 

SEE ALSO 

ppmquant(l), ppm( 5 ) 

BUGS 

It'sacsh script, csh scripts are not portable to System V. Scripts in general are not portable to non-UNIX environments 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

27 July 1990 



ppmqvga 

ppmqvga — 8-plane quantization 

SYNOPSIS 

ppmqvga [ options ] [ input file ] 

DESCRIPTION 

ppmqvga quantizes PPM files to eight planes with optional F loyd-Stei nberg dithering. Input is a PPM file from thefile 
named, or standard input if no file is provided. 

OPTIONS 

-d dither Apply Floyd-Steinberg dithering to thedata 

-q quiet Producesno progress reporting, and no terminal output unlessan error occurs 

-v verbose Produces additional output describing the number of colors found, and some information on the resulting 
mapping. M ay be repeated to generate loads of internal table output, but generally only useful once 

EXAMPLES 

ppmqvga -d my_image.ppm j ppmtogif >my_image.gif 


tgatoppm zombie.tga | ppmqvga | ppmtotif > zombie.til 



ppmshift 


H 

SEE ALSO 

ppmquant 

DIAGNOSTICS 

Error messages if problems; various levelsof optional progress reporting. 

AUTHORS 

Original by Lyle Rains (irains@netcom.com) asppmq256 and ppmq256fs combined; documented and enhanced by Bill Davidsen 

(davidsen@crd.ge.com). 

COPYRIGHT 

Copyright© 1991,1992 by Bill D avidsen, all rights reserved. The program and documentation may be freely distributed by 
anyonein source or binary format. Please clearly note any changes. 

Local 


ppmrelief 

ppmreiief- Run a Laplacian relief filter on a portable pixmap 

SYNOPSIS 

ppmrelief [ppmfiI e ] 

DESCRIPTION 

ppmrelief reads a portable pixmap as input, does a Laplacian relief filter, and writes a portable pixmap as output. 

The Laplacian relief filter isdescri bed in Beyond Photography by Holzmann, equation 3.19. It'sa sort of edge-detection. 

SEE ALSO 

pgmbentley(l), pgmoil(l), ppm(5) 

AUTHOR 

C opyright© 1990 by W iIson Bent (whb@hoh- 2 .att.com). 

11 January 1991 


ppmshift 

ppmshift— Shift lines of a portable pixmap left or right by a random amount 

SYNOPSIS 

ppmshift shi ft [ppmf i I e ] 

DESCRIPTION 

ppmshift reads a portable pixmap as input and shifts every row of image data to the left or right by a certain amount. The 
shift parameter determines by how many pixelsa row isto be shifted at most. 

Another one of those effects I intended to use for M PEG tests. Unfortunately, this program will not help me here-it creates 
patterns that are too random to be used for animations Still, it might give interesting results on still images. 
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EXAMPLE 

C heck this out: Save your favorite model's picture from something like ait. binaries. pictures. supermodeis (okay, or from 
any other picture source), convert it to ppm, and process it like this assuming the picture is 800x600 pixels 

1 . Take the upper half and leave it like it is: pnmcut 0 0 800 300 cs.ppm >upper.ppm. 

2 . Take the lower half, flip it upside down, dim it, and distort it a little: pnmcut 0 300 800 300 cs.ppm | pnmfiip -tb ] 

ppmdim 0.7 j ppmshift 10 >lower.ppm. 

3. C oncatenate the two pieces: pnmcat -tb upper.ppm lower.ppm >newpic.ppm. 

The resulting picture looks like the image being reflected on a water surface with slight ripples 

SEE ALSO 

ppm( 5 ), pnmcut(l), pnmflip(l), ppmdim(l), pnmcat(l) 

AUTHOR 

Copyright© 1993 by Frank N eumann. 

16 N ovember 1993 


ppmspread 

ppmspread- D isplace a portable pixmap's pixels by a random amount 

SYNOPSIS 

ppmspread amount [ppmf i I e ] 

DESCRIPTION 

ppmspread reads a portable pixmap as input and moves every pixel around a bit relative to its original position, amount 
determines by how many pixels a pixel is to be moved around at most. 

Pictures processed with thisfilter will seem to be somewhat dissolved or unfocussed (although they appear more coarse than 
images processed by something like pnmconvoi). 

SEE ALSO 

ppm( 5 ), pnmconvol(l) 

AUTHOR 

Copyright© 1993 by Frank N eumann. 

16 N ovember 1993 


ppmtoacad 

ppmtoacad- Convert portable pixmap to AutoCAD database or slide 

SYNOPSIS 

ppmtoacad [-dxb][-poly][-background col our ][-white][-aspect rat i o ][- 8 ][ppmf i I e] 

DESCRIPTION 

ppmtoacad reads a portable pixmap as input. Produces an AutoCAD slidefileor binary database import (DXB) file as output. 
If no ppmfiie isspecified, input is read from standard input. 



ppmtoacad 




OPTIONS 


-poly 


An AutoCAD binary database import (DXB) file is written. This file is read with theDXBiN 
command and, once loaded, becomes part of the AutoCAD geometrical database and can be 
viewed and edited like any other object. Each sequence of identical pixels becomes a separate object 
in thedatabase; thiscan result in very large AutoCAD drawing files However, if you want to trace 
over a bitmap, it lets you zoom and pan around the bitmap as you wish. 

Ifthe-dxb option is not specified, the output of ppmtoacad isan AutoCAD slidefile Normally, 
each row of pixels is represented by an AutoCAD line entity. If -poiy is selected, the pixels are 
rendered as filled polygons. If the slide is viewed on a display with higher resolution than thesource 
pixmap, this will cause the pixelsto expand instead of appearing asdiscrete lines against the screen 
background color. Regrettably, this representation yields slide files that occupy more disc space and 
take longer to display. 

Most AutoCAD display drivers can be configured to use any available color as the screen back¬ 
ground. Some users prefer a black screen background, others white while splinter groups advocate 
burnt ocher, tawny puce, and shocking gray. Discarding pixels whose closest AutoCAD color 
representation isequal to the background color can substantially reduce the size of the AutoCAD 
database or slidefile needed to represent a bitmap. If no -background color is specified, the screen 
background color isassumed to be black. Any AutoCAD color number may be specified as the 
screen background; color numbers are assumed to specify the hues defined in the standard 
AutoCAD 256-color palette. 

Because many AutoCAD users choose a white screen background, thisoption isprovided asa 
short-cut. Specifying -white is identical in effect to -background i. 

If the source pixmap had nonsquare pixels, the ratio of the pixel width to pixel ha'ght should be 
specified as ratio. The resulting slide or DXB file will be corrected so that pixels on the AutoCAD 
screen will be square. For example, to correct an image made for a 320x200 VGA/M CGA screen, 
Specify -aspect 0 . 8333 . 

Restricts the colors in theoutput file to the eight RGB shades 


All flags can be abbreviated to their shortest unique prefix. 


BUGS 

AutoCAD hasa fixed palette of 256 colors, distributed along the hue, lightness, and saturation axes Pixmaps that contain 
many nearly identical colors, or colors not closely approximated by AutoCAD's palette may be poorly rendered, 
ppmtoacad works best if the system cdisplaying itsoutput supports the full 256 color AutoCAD palette. Monochrome, 
8 -color, and 16-color configurations will produce less than optimal results 

When creating a DXB file or a slide file with the -poiy option, ppmtoacad finds both vertical and horizontal runs of identical 
pixels and consolidates them into rectangular regions to reduce the size of the output file This iseffectivefor images with 
large areas of constant color, but it's no substitute for true raster to vector conversion. In particular, thin diagonal lines are 
not optimized at all by this process 
Output files can be huge. 


SEE ALSO 

AutoCAD Reference M anual: "Slide File Format" and "Binary Drawing Interchange (DXB) Files"; ppm( 5 ) 


AUTHOR 

John Walker 
Autodesk SA 

Avenue desChamps-M ontantsl4b 
CH-2074 MARIN 

Suiss^Schweiz/Svi zzera/ Svizra/ Swi tzerl an d 
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Usenet: kelvin@Autodesk.com 

Fax: 038/33 88 15 

Voice 038/33 76 33 

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is 
hereby granted, without any conditions or restrictions. T hissoftware is provided "as is" without express or implied warranty. 
AutoCAD and Autodesk are registered trademarks of Autodesk, Inc. 

10 October 1991 


ppmtobmp 

ppmtobmp— Convert a portable pixmap into a BM P file 

SYNOPSIS 

ppmtobmp [ -wi ndows ] [- os2 ] [ppmf i I e ] 

DESCRIPTION 

ppmtobmp reads a portable pixmap as input and produces a M icrosoft Windows or OS/2 BMP fileasoutput. 

OPTIONS 

-windows Tel Is the program to produce a M icrosoft W indows BM P file 
-os 2 Tel Is the program to produce an 0 S/2 BM Pfile. (T his is the default.) 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

bmptoppm(l), ppm(5) 

AUTHOR 

Copyright© 1992 by David W. Sanderson. 

26 October 1992 


ppmtogif 

ppmtogif- Convert a portable pixmap into a GIF file 

SYNOPSIS 

ppmtogif [-interlace][-sort][-map ma pf i I e][-transparent col or ][ppmf i I e] 

DESCRIPTION 

ppmtogif reads a portable pixmap asinput and producesaGIF fileasoutput. 

OPTIONS 

-interlace Tells the program to produce an interlaced GIF file. 

-sort ProducesaGIF file with a sorted colormap. 

-map mapfiie U ses the colors found in themapf i i e to create the colormap in the GIF file, instead of thecolors 

from ppmfiie. Themapf i i e can beany ppm file; all that matters isthe colors in it. If thecolors in 
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ppmf iie do not match those in mapf iie, they are matched to a "best match." A (much) better result 
can beobtained by using the following filter in advance: 
ppmquant -floyd -map mapfile 

-transparent color M arkthegiven colorastransparentin theGIF file. Thecolorisspecified asin ppmmake(l). Note 
that this option outputsaG I F89a format file, which might not be understood by your software. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

giftoppm(l), ppmquant(l), ppm(5) 

AUTHOR 

Based onGiFENcoD by David Rowley (mgardi@watdcsu.waterioo.edu). Lempel-Zivcompression based on compress. 

Copyright© 1989 byjef Poskanzer. 

30Junel993 


ppmtoicr 

ppmtoicr- Convert a portable pixmap into N C SA IC R format 

SYNOPSIS 

ppmtoicr [-windowname name][-expand expand][-display di s pi ay][-rle][ppmf i I e] 

DESCRIPTION 

ppmtoicr reads a portable pixmap file as input and produces an NCSATelndt Interactive Color Raster graphic file as output. 
If ppmfiie is not supplied, ppmtoicr will read from standard input. 

Interactive Color Raster (ICR) isa protocol for displaying raster graphics on workstation screens T he protocol is imple¬ 
mented in NCSA Telnet for the M acintosh version 2.3. The ICR protocol shares characteristics of the Tektronix graphics 
terminal emulation protocol. For example escape sequences are used to control the display. 

ppmtoicr will output the appropriate sequences to create a window of the dimensions of the input pixmap, create a colormap 
of up to 256 colors on the display, then load the picture data into the window. 

Note that there is no icrtoppm tool; this transformation is one-way. 

OPTIONS 

-windownamename Output will be displayed in name. (Default is to useppm-fiie or "untitled" if standard input is read.) 
-expandexpand Output will be expanded on display by factor expand. (For example, a value of 2 will cause four pixels to be 
displayed for every input pixel.) 

-dispiaydi s pi ay Output will be displayed on screen numbered display. 

-rie Use run-length encoded format for display. (Thiswill nearly always result in a quicker display, but may 

skew the colormap.) 

EXAMPLES 

This displays a ppm file using the protocol: 

ppmtoicr ppmfiie 

Thiswill create a window named ppmfiie on the display with the correct dimensionsfor ppmfiie, create and download a 
colormap of up to 256 colors, and download the picture into the window. The same effect may be achieved by the following 
sequence: 
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ppmtoicr ppmfile > filename 

To display a GIF file using the protocol in a window titled after the input file, zoom thedisplayed image by a factor of 2, 
and run-length encode the data: 

giftoppm giffile | ppmtoicr -w giffile -r -e 2 

BUGS 

The protocol uses frequent f flush calls to speed up display. If the output is saved to afilefor later display via cat, drawing 
will be much slower. In either case increasing the Blocksize limit on the display will speed up transmission substantially. 

SEE ALSO 

ppm(5) 

NCSA T dnet for theM acintod 1, U niversity of Illinois at U rbana-C hampaign (1989) 

AUTHOR 

Copyright© 1990 by Kanthan Pillay (svpiiiay@Princeton.EDu), Princeton University Computing and Information Technol¬ 
ogy 

30 July 1990 


ppmtoilbm 

ppmtoiibm—Convert a portable pixmap into an ILBM file 

SYNOPSIS 

ppmtoilbm [-maxplanes]-mp N][-fixplanes|-fp N][-ham6|-ham8][-dcbits-dcplanesrgb] 

[-normal!-hamif]-hamforce]-24if]-24force| -dcif]-deforce!-cmaponly] [-ecs!-aga] 

[- compress!-nocompress] [-cmethod type][-mapppmfile] [-savemem] [ppmfile] 

DESCRIPTION 

ppmtoilbm reads a portable pixmap as input and produces an ILBM file as output. Supported ILBM types are th e fo I lo wi n g: 
Normal ILBMswith 1-16 planes 
Amiga HAM with 3-16 planes 
24-bit 

Colormap (bmhd and cmap chunk only, nPianes = 0) 

U nofficial direct color 1-16 planesfor each color component 

Chunks written: bmhd, cmap, camg (only for HAM), body (not for colormap files) unofficial dcol chunk for direct color ILBM 

OPTIONS 

Options marked with (*) can be prefixed with no, for example, -nohamif. All optionscan be abbreviated to their shortest 
unique prefix. 

-maxplanes ] - mp n (default 5, minimum 1, maximum 16) M aximum planes to write in a normal ILBM . If the 

pixmap does not fit into n planes, ppmtoilbm writes a HAM file (if -hamif is used), a 24-bit 
file (if -24if is used), a direct color file (if -dcif isused). or aborts with an error. 

-fixplanes ; -fp n (min 1, max 16) If a normal ILBM is written, it will have exactly n planes 

-hambits ! -hampianes n (default 6, min 3, max 16) Select number of planesfor H AM picture Thecurrent Amiga 
hardware supports 6 and 8 planes, so for now you should only use this values. 
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-normal (default) 



-deforce (*) 

-debits | -deplanes r g b 
-ecs (default) 




-compress (*) (default), 
-cmethod none[byteruni 


-map ppmf i I e 

-cmaponly 

-savemem 


Turns Off -hamif/-24if/-dcif, -hamforce/-24force/-deforce and -cmaponly. Also SdtS 
compression type to byteruni. 

W rite a H AM /24-bit/direct color file if the pixmap does not fit into maxpianes pianes. 

W rite a H AM /24-bit/direct color file. 

(default 5, min 1, max 16). Select number of bitsfor red, green, and blue in a direct color 
ILBM. 

Shortcut for: -hamplanes 6 -maxpianes 5 
Shortcut for: -hamplanes 8 -maxpianes 8 
Shortcut for: -hamplanes 6 -hamforce 
Shortcut for: -hamplanes 8 -hamforce 

Compress the body chunk. The default compression method is byteruni. Compression 
requires building the ILBM imagein memory; turning compression off allows stream¬ 
writing of the image but the resulting file will usually be 30 percent to 50 percent larger. 
Another alternative is the -savemem option; this will keep memory requirements for 
compression at a minimum, but is very slow. 

Writeanormal ILBM using the colors in ppmf i i e asthecolormap. Thecolormapfilealso 
determines the number of planes a -maxpianes or -fixpianes option is ignored. 

W rite a colormap file: only bmhd and cmap chunks, no body chunk, nPianes = 0 . 

Seethe -compress option. 


BUGS 

HAM pictures will always get a grayscale colormap; a real color selection algorithm might give better results. On the other 
hand, this allows row-by-row operation on HAM images, and all HAM images of the same depth (number of planes) sharea 
common colormap, which is useful for building HAM animations. 

REFERENCES 

AmigaROM Kernel ReferenceM anual— Devices(Third Edition), Addison Wesley, ISBN 0-201-56775-X 

SEE ALSO 

ppm(5), ilbmtoppm(l) 

AUTHORS 

Copyright© 1989 byjef Poskanzer; modified October 1993 by Ingo Wilken (ingo.wiiken@informatik.uni-oidenburg.de). 

31 October 1993 


ppmtomap 

ppmtomap- Extract all colors from a portable pixmap 

SYNOPSIS 

ppmtomap [-sort][-square] [ppmfiIe ] 

DESCRIPTION 

ppmtomap reads a portable pixmap as input and produces a portable pixmap as output, representing a colormap of the input 
file. All n different colors found are put in an N XI portable pixmap. This colormap file can be used asarnapfileforppmquant 
Or ppmtogif. 
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OPTIONS 

-sort Produces a portable pixmap with the colors in some sorted order 

-square Produces a (more or less) square output file instead of putting all colors on the top row 

All flags can be abbreviated to their shortest unique prefix. 

WARNING 

If you want to use theoutput file as a mapfilefor ppmtogtf , you first have to do a ppmquant 256 because ppmtomap is not 
limited to 256 colors (but to 65536). 

SEE ALSO 

ppmtogif(1), ppmquant(l), ppm(5) 

AUTHOR 

M arcel W ijkstra (wijkstra@fwi.uva.m) 

Copyright© 1989 byjef Poskanzer. 

11 August 1993 


ppmtomitsu 

ppratoraitsu—Convert a portable pixmap to a M itsubishi S340-10 file 

SYNOPSIS 

ppmtomitsu [-sharpness va! [[-enlarge v a I [[-media stri n g ][-copy val ] 
[ -dpi300] [ -tiny] [ppmfile] 


DESCRIPTION 


ppmtomitsu reads a portable pixmap as input and converts it into a format suitable to be printed by a M itsubishi S340-10 
printer, or any other M itsubishi color sublimation printer. 


The M itsubishi S340-10 Color Sublimation printer supports 24-bit color. I mages of the available sizes take so long to 
transfer that there is a fast method, employing a lookup table that ppmtomitsu will use if there is a maximum of 256 colors in 
the pixmap. ppmtomitsu will try to position your image to the center of the paper, and will rotate your image for you ifxsize 
is larger than ysize. If your image is larger than the media allows, ppmtomitsu will quit with an error message (Wedecided 
that the medi a were too expensive to have careless users produce misprints) After data transmission has started, the job can't 
be stopped in a sane way without resetting the printer.The printer understands putting together images in the printer's 
memory; ppmtomitsu doesn't utilize this as pnmcat and so on provide the same functionality and let you view the result 
onscreen, too. The S340-10 isthe lowest common denominator printer; for higher resolution printers, there's the dpi30@ 
option. The other printers also support higher values for enlarge eg, but I don't think that's essential enough to warrant a 
change in the program. 


-sharpness 1-4 
-enlarge 1-3 
-media A, A4, AS, A4S 


-copy 1-9 


-dpi300 


Sharpness designation. Default isto use the current sharpness 
Enlarge by a factor; default is i (no enlarge) 

Designatethemediayou'reusing. Default isii 84 x 1350, which will fit on any media. A is 1216 x 
1350, A4 is 1 184 x 1452, AS is 1216 x 1650, and A4S is 11 84 x 1754. A warning: If you specify a 
different media than the printer currently has the printer will wait until you put in the correct 
media or switch it off. 

T he number of copies to produce. Default isi. 

Double the number of allowed pixels for a S3600-30 Printer in S340-10 compatibility mode. (The 
S3600-30 has 300dpi.) 
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-tiny M emory-safing, but always slow. The printer will get the data line-by-line in 24-bit. It's probably a 

good idea to use this if your machine starts paging a lot without this option. 


REFERENCES 

M itsubishi Sublimation Full Color Printer S340-10; Specifications of Parallel Interface LSP-F0232F 

SEE ALSO 

ppmquant(l), pnmscale(l), ppm(5) 

BUGS 

Wedidn'tfind any-ydt. Besides, they're called features anyway:-) If you should find one, please e-mail me at the following 
address 

AUTHOR 

Copyright© 1992,1993 by S. PetraZeidler, M PIFR Bonn,Germany (spz@speckiec.mpifr-bonn.mpg.de). 

29 January 1992 
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ppmtopcx- Convert a portable pixmap into a PCX file 

SYNOPSIS 

ppmtopcx [ppmfi I e] 

DESCRIPTION 

ppmtopcx reads a portable pixmap as input and produces a PC X file as output. 

SEE ALSO 

pcxtoppm(l), ppm(5) 

AUTHOR 

Copyright © 1990 by M ichael Davidson. 

9 April 1990 


ppmtopgm 

ppmtopgm- Convert a portable pixmap into a portable graymap 

SYNOPSIS 

ppmtopgm [ppmf i I e ] 

DESCRIPTION 

ppmtopgm reads a portable pixmap as input and produces a portable graymap as output. The quantization formula used is 
.299 r +.587 g + .114 b. 

Note that although thereisapgmtoppm program, it is not necessary for simple conversions from pgm to ppm, because any ppm 
program can read pgm (and pbm ) files automagically, pgmtoppm is for colorizing a pgm file. Also, see ppmtorgb3 for a different 
way of converting color to gray. 
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QUOTE 

Cold-hearted orb that rules the night 
Removes the colors from our sight 
Red isgray, and yellow white 
But we decide which isright 
And which isa quantization error. 

SEE ALSO 

pgmtoppm(l), ppmtorgb3(l), rgb3toppm(l), ppm(5), pgm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

23 December 1988 


ppmtopil 

ppmtopii — Convert a portable pixmap into an Atari D egas PI 1 file 

SYNOPSIS 

ppmtopil [ppmfile] 

DESCRIPTION 

ppmtopii reads a portable pixmap as input and produces an Atari D egas PI 1 file as output. 

SEE ALSO 

piltoppm(l), ppm(5), pbmtopi3(l), pi3topbm(l) 

AUTHOR 

Copyright© 1991 by Steve Belczyk (seb3@gte.com) and Jef Poskanzer. 

19 July 1990 


ppmtopict 

ppmtopict— Convert a portable pixmap into a M acintosh PICT file 

SYNOPSIS 

ppmtopict [ p p mf i I e ] 

DESCRIPTION 

ppmtopict reads a portable pixmap asinput and producesa M acintosh PICT file as output. 

Thegenerated file is only the data fork of a picture. You will need a program such asmcvert to generate a M acbinary or a 
BinH ex file that containsthenecessary information to identify thefile as a PICT file to M acOS. 

Even though PICT supports2 and 4 bits per pixel, ppmtopict always generates an 8-bits-per-pixel file. 

BUGS 

The picture size field isonly correct if theoutput isto a file because writing into thisfield requires seeking backwards on a 
file. H owever, the PICT documentation seems to suggest that thisfield is not critical anyway because it is only the lower 16 
bits of the picture size 
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SEE ALSO 

picttoppm(l), ppm(5), mcvert(l) 

AUTHOR 

Copyright® 1990 by Ken Yap (ken@cs.rocester.edu). 

15 April 1990 


ppmtopj 

ppmtopj -Convert a portable pixmap to an HP PaintJet file 

SYNOPSIS 



DESCRIPTION 

ppmtopj reads a portable pixmap asinputand converts it into a format suitable to be printed by an H P PaintJet printer. 

For best results, the input file should be in 8-color RGB form; that is, it should have only the eight binary combinations of 
full-on and full-off primaries You could get this by sending the input file through ppmquant -map with amapfilesuch as 



0 r else you could use ppmdither -red 2 -green 2 -blue 2 . 

OPTIONS 

-rie Run-length encode the image. (Thiscan result in largerimages) 

-back Enhancetheforeground by indicating if the background is light or dark compared to the foreground, 

-render aig Use an internal rendering algorithm (default dither). 

-gamma i nt Gamma correct the image using the integer parameter asa gamma (default 0 ). 

-center C enter the image to an 8.5 by 11 page 

-xpos pos Movebypos pixels in thex direction. 

-ypos pos Movebypos pixels in they direction. 

REFERENCES 

HP PaintJet XL Color GraphicsPrinter U ser'sGuide 

SEE ALSO 

pnmdepth(l), ppmquant(l), ppmdither(l), ppm(5) 

BUGS 

M ost of the options have not been tested because of the price of the paper. 

AUTHOR 

Copyright© 1991 by C hristos Zoulas. 



13 July 1991 
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ppmtopjxi—Convert a portable pixmap into an H P PaintJet XL PCL file 

SYNOPSIS 

ppmtopj xl [-nopack] [-gamma <n> ] [-presentation] [-dark] [-diffuse] 

[-cluster] [-dither] [-xshift <s> ] [-yshift <s> ] [-xshift <s> ] [-yshift <s> ] 
[-xsize]-width]-xscale <s> ] [-ysize]-height]-yscale <s> ] [ppmfile] 


DESCRIPTION 

ppmtopjxi reads a portable pixmap as input and produces a PCL file suitable for printing on an H P PaintJet XL printer as 
output. 

The generated file is not suitablefor printing on a normal Printjet printer. The -nopack option generates a file that does not 
use the normal TIFF 4.0 compression method. Thisfile might be printable on a normal PaintJet printer (not an XL). 

The -gamma option sets the gamma correction for the image The useful range for the PaintJ et XL is approximately 0.6 
to 1.5. 

The rendering algorithm used for images can be altered with the -dither, -cluster, and -diffuse options These options 
select ordered dithering, clustered ordered dithering, or error diffusion, respectively. The -dark option can be used to 
enhance images with a dark background when they are reduced in size The -presentation option turns on presentation 
mode in which two passes are made over the paper to increase ink density. This should be used only for images where 
quality is critical. 

Theimagecan be resized by setting the -xsize and -ysize options The parameter to either of these options is interpreted as 
the number of dots to set the width or height to, but an optional dimension of pt (points), dp (decipoints), in (inches), or cm 
(centimeters) may be appended. If only one dimension is specified, the other will be scaled appropriately. 

The options -width and -height are synonyms of -xsize and -ysize. 

The -xscaie and -yscale options can alternatively be used to scale the image by a simple factor. 

T he i mage can be shifted on the page by usi ng the -xshift and -yshift options. T hese move the image the specified 
dimensions right and down. 

SEE ALSO 

ppm(5) 

AUTHOR 

Angus Duggan 


ppmtopuzz 

ppmtopuzz— Convert a portable pixmap into an Xll puzzle file 

SYNOPSIS 

ppmtopuzz [ppmf i I e ] 

DESCRIPTION 

ppmtopuzz reads a portable pixmap as input and produces an Xll puzzle file as output. A puzzle file is for use with thepuzzie 
program included with theXll distribution; puzzle’s -picture flag lets you specify an image file 



ppmtosixel 


425 


SEE ALSO 

ppm(5), puzzle(l) 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

22 August 1990 


ppmtorgb3 

ppmtorgb3 — Separate a portable pixmap into three portable graymaps 

SYNOPSIS 

ppmtorgb3 [ppmf i I e] 

DESCRIPTION 

ppmtorgb3 reads a portable pixmap as input and writes three portable graymaps as output, one each for red, green, and blue. 
The output filenames are constructed by taking the input filename stripping off any extension, and appending .red, .grn, 
and .blu. For example separating lenna. ppm would result in lenna.red, lenna.grn, and lenna.blu. If the input comes from 
stdin, the names are noname, red, noname.grn, and noname.blu. 


SEE ALSO 

rgb3toppm(l), ppmtopgm(l), pgmtoppm(l), ppm(5), pgm(5) 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

10 January 1991 


ppmtosixel 

ppmtosixei- Convert a portable pixmap into DEC sixel format 

SYNOPSIS 

ppmtosixel [-raw][-margin][ppmfiIe ] 

DESCRIPTION 

ppmtosixel reads a portable pixmap asinput and produces sixel commands(SIX) as output. The output is formatted for color 
printing, for example, for a D EC LJ 250 color inkjet printer. 

If RGB values from the PPM file do not havemaxvai=i 00 , the RGB values are rescaled. A printer control header and a color 
assignment table begin the SIX file Image data iswritten in a compressed format by default. A printer control footer ends 
the image file. 

OPTIONS 

-raw If specified, each pixel will beexplicitly described in the image file. If -raw is not specified, output will default to 
compressed format in which identical adjacent pixels are replaced by repeat pixel commands A raw file is often 
an order of magnitude larger than a compressed file and prints much slower. 

-margin If -margin is not specified, the image will start at the left margin (of thewindow, paper, or whatever). If -margin is 
specified, a 1.5 inch left margin will offset the image 



Parti: User Commands 


426 


PRINTING 

Generally, sixel files must reach the pri nter unfiltered. Usetheipr -x option or cat filename > /dev/ttye?. 

BUGS 

Upon rescaling, truncation of the least significant bits of RGB values may result in poor color conversion. If the original 
PPM maxvai was greater than 100, rescaling also reduces theimagedepth. Whilethe actual RGB values from the ppm file are 
more or less retained, the color palette of the LJ 250 may not match the colorson your screen. This seems to be a printer 
limitation. 

SEE ALSO 

ppm(5) 

AUTHOR 

Copyright© 1991 by Rick Vinci. 

26 April 1991 


ppmtotga 

ppmtotga- Convert portable pixmap into a Truevision Targafile 

SYNOPSIS 

ppmtotga [-mono!-cmap]-rgb][-norle][ppmf i Ie ] 

DESCRIPTION 

ppmtotga reads a portable pixmap as input and produces a T rueV ision T arga file as output. 

OPTIONS 

-mono ForcesT arga file to be of type 8-bit monochrome. Input must be a portable bitmap ora portable graymap. 

-cmap ForcesTargafileto be of type 24-bit colormapped. Input must be a portable bitmap, a portable graymap, ora 
portable pixmap containing no more than 256 distinct colors. 

-rgb ForcesT argafileto be of type 24-bit unmapped color. 

-norie D isables run-length encoding, in case you have a T arga reader that can't read run-length encoded files. 

All flags can be abbreviated to their shortest unique prefix. If no file type is specified, the most highly constained compatible 
type is used, where monochrome is more constained than colormapped, which is in turn more constained than unmapped. 

BUGS 

Does not support all possibleTarga file types Should really be in pnm, not ppm. 

SEE ALSO 

tgatoppm(l), ppm(5) 

AUTHOR 

Copyright© 1989,1991 by M ark Shand and Jef Poskanzer. 


28 October 1991 
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ppmtouii— Convert a portable pixmap into a M otif UIL icon file 

SYNOPSIS 

ppmtouil [-name u i I n a me][p p mf i I e ] 

DESCRIPTION 

ppmtouii reads a portable pixmap as input and produces a M otif UIL icon file as output. 

If the program was compiled with an rgb database specified, and an RGB value from the ppm input matches an RGB value 
from the database, then the corresponding color name mnemonic is printed in the UI L's colormap. If no rgb database was 
compiled in, or if the RGB values don't match, then the color will be printed with the#RGB, #rrggbb, #rrrgggbbb, or 
#rrrrggggbbbb hexadecimal format. 

OPTIONS 

-name Allows you to specify the prefix string that is printed in the resulting UIL output. If not specified, it will default to 
thefilename (without extension) of theppmfiie argument. If -name is not specified and no ppmfiie isspecified 
(that is, piped input), the prefix string will default to the string "noname". 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

ppm(5) 

AUTHOR 

Converted byjef Poskanzerfrom ppmtoxpm. c, which is copyright© 1990 by M ark W. Snitily. 

31 August 1990 
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ppmtoxpm- Convert a portable pixmap into an Xll pixmap 

SYNOPSIS 

ppmtoxpm [-name <xpmname>] [-rgb <rgb-textfile>][<p p mf i I e >] 

DESCRIPTION 

ppmtoxpm reads a portable pixmap as input and produces an X11 pixmap (version 3) as output that can be loaded directly by 
theXPM library. 

The -name option allows you to specify the prefix string which is printed in the resulting XPM output. If not specified, it will 
default to thefilename (without extension) of theppmfiie argument. If -name is not specified and ppmfiie is not specified 
(that is, piped input), the prefix string will default to the string "noname". 

The -rgb option allows you to specify an Xll rgb text file for the lookup of color name mnemonics ThisRGB text file is 
typically the /usr/iib/xn/rgb.txt of the M IT Xll distribution, but any file using the same format may be used. When 
specified and an RGB value from the ppm input matches an RGB value from the <rgb-textfiie>, then the corresponding 
color name mnemonic is printed in the X P M 'scolormap. If - rgb is not specified, or if the RG B values don't match, then the 
color will be printed with the#RGB, #rrggbb, #rrrgggbbb, or #rrrrggggbbbb hexadecimal format. 

All flags can be abbreviated to their shortest unique prefix. 
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For example, to convert thefile dot (found in /usr/inciude/xn/bitmaps), from xbm to xpm.you could specify 

xbmtopbm dot | ppmtoxpm -name dot 

or, with an rgb text file (in the local directory) 

xbmtopbm dot | ppmtoxpm -name dot -rgb rgb.txt 

BUGS 

An option to match the closest (rather than exact) color name mnemonic from the rgb text would be a desirable enhance¬ 
ment. 

Truncation of the least significant bits of an RGB value may result in nonexact matches when performing color name 
mnemonic lookups. 

SEE ALSO 

PP™(5) 

XPM M anual byArnaud LeHors(lehors@mirsa.inria.fr). 

AUTHOR 

Copyright © 1990 by M ark W. Snitily. This tool was developed for Schlumberger Technologies, ATE Division, and with 
their permission is being madeavailableto the public with the above copyright notice and permission notice 
Upgraded to XPM 2 by Paul Breslaw, Mecasoft SA, Zurich, Switzerland (paui@mecazh.uu.ch); Thu, Nov8,16:01:17,1990. 
Upgraded to XPM version 3 byArnaud leHors (iehors@mirsa.inria.fr). 

9 April 1991 
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ppmtoyuv— Convert a portable pixmap into an AbekasYUV file 

SYNOPSIS 

ppmtoyuv [ppmfile] 

DESCRIPTION 

ppmtoyuv reads a portable pixmap asinput and produces an AbekasYUV fileasoutput. 

SEE ALSO 

yuvtoppm(l), ppm(5) 

AUTHOR 

M arc Boucher (<marc@P0stima9e.coM>), based on Example Conversion Program, A60/A64 Digtal Video InterfaceM anual, 
page 69. Copyright© 1991 by DH D Post I mage Inc. Copyright© 1987 by Abekas Video Systems Inc. 

25 March 1991 
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ppmtoyuvspiit— Convert a portable pixmap into three subsampled rawYUV files 

SYNOPSIS 


ppmtoyuvsplit 


[ppmf i I e ] 
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DESCRIPTION 

ppmtoyuvsplit reads a portable pixmap as input and produces three raw files- basename.Y, basename.U, and basename.v-as 
output. These files are the subsampled raw YU V representation of the input pixmap, as required by the Stanford M PEG 
code. The subsampling isdone by arithmetic mean of 4 pixels colors into one TheYUV values are scaled according to 
CCIR.601, as assumed by MPEG. 

SEE ALSO 

mpeg(l), ppm(5) 

AUTHOR 

Copyright© 1993 by Andre Beck (AndreBeck@IRS.Inf.TU-Dresden.de). Based on ppmtoyuv.c. 

9 September 1993 


pr 

pr— Convert text filesfor printing 

SYNOPSIS 

pr [+PAGE] [-COLUMN] [-abcdfFmrtv] ]-e[in-tab-char[in-tab-width]]] [-h header] 
]-i[out-tab-char[out-tab-width] ] ] [-1 page-length] [-n[number-separator[digits]]] 

]-o left-margin] ]-s[column-separator]] ]-w page-width] [--help] [-- version] [file...] 


DESCRIPTION 

This manual page documents the GN U version of pr. pr prints on the standard output a paginated and optionally 
multicolumn copy of the text files given on the command line, or of the standard input if no files are given or when the 
filename - is encountered. Form feeds in the input cause page breaks in the output. 


OPTIONS 

PAGE 

-COLUMN 


-e[in-tab-char 

[in-tab-width]] 


Begin printing with page page. 

Produce coLUMN-column output and print columns down. The column width is automatically 
decreased as column increases; unless you use the -w option to increase the page width as well, this 
option might cause some columnsto be truncated. 

Print columns across rather than down. 

Balance columns on the last page. 

Print control characters using hat notation (for example, A G); print other unprintable characters in 
octal backslash notation. 

D ouble-space the output. 

Expand tabs to spaceson input. Optional argument in-tab-char is the input tab character, default 
tab. 0 ptional argument in-tab-width isthe input tab character's width, default 8 . 

Useaform feed instead of newlines to separate output pages 
Replacethefilenamein the header with the string header. 

Print a usage message and exit with a nonzero status. 

Replacespaceswith tabs on output. Optional argument out-tab-char isthe output tab character, 
default tab. Optional argument out-tab-width is the output tab character's width, default 8 . 

Sdt the page length to page- 1 ength lines. The default is 66. If page- 1 ength is less than 10, the 
headers and footers are omitted, as if the -t option had been given. 

Print all files in parallel, one in each column. 
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-n[number-separator 

[digits]] 


-w page- m dth 


Precede each column with a linenumber; with parallel files, precede each line with alinenumber. 

0 ptional argument number-separator is the character to print after each number, default tab. 

0 ptional argument digits is the number of digits per line number, default 5. 

Offset each line with a margin i eft-margi n spaces wide The total page width isthisoffset plus the 
width set with the -w option. 

Do not print a warning message when an argument file cannot be opened. Failure to open a file 
still makes the exit status nonzero, however. 

Separate columns by the si ngl e character c o i umn-separator, default tab, instead of spaces 
Do not print the 5-line header and the 5-linetrailer that are normally on each page and do not fill 
out the bottoms of pages (with blank lines or form feeds). 

Print unprintable characters in octal backslash notation. 

Print version information on standard output then exit. 

Sdt the page width to page-wi dt h columns The default is 72. 

GNU Text Utilities 


ps 

ps- Report process status 

SYNOPSIS 

ps [-][lujsvmaxScewhrnu][txx][0[+|-]kl[[+j-]k2...]] [pids] 

There are also two long options: 

--sortX[+]-]key[,[ + ] - ]key[,...] ] 

--help 

M ore long options are on the way... 

DESCRIPTION 

ps gives a snapshot of the current processes. If you want a repetitive update of this status, use top. This man page documents 
the /proc-based version of ps, or tries to. 

COMMAND-LINE OPTIONS 

Command-line arguments may optionally be preceded by a -, but there is no need for it. T here are also some long options in 
GNU style; see the following subsection for those. 

1 Long format, 

u User format: gives username and start time, 

j J obs format: pgid sid. 

s Signal format, 

v vm format. 

m Displays memory information (combinewith p flag to get number of pages), 

f Forestfamilytreeformatforcommand line 

a Show processes of other users too. 

x Show processes without controlling terminal, 

s Add child cpu time and page faults 

c C ommand name from task struct, 

e Show environment after command line and +. 



pr 




w Wide output: don't truncate command lines to fit on one line 

h N o header, 

r Running procs only, 

n N umeric output for user and wchan. 

txx 0 nly procs with controlling tty xx; use for xx the same letters as shown in the tt field.The 

tty name must be given immediately after the option, with no intervening space, for 
example, ps -tvi. 

0 [+!-]ki[,[+|-]k 2 [,...]] 0 rder the process listing according to the multilevel sort specified by the sequence of short 

keys from sort keys, «, k 2 , .... Default order specifications exist for each of the various 
formats of ps. These are overridden by a user-specified ordering. The + is quite optional, 
merely reiterating the default direction on a key. - reverses direction only on the key it 
precedes. As with t and pids, the o option must be the last option in a single command 
argument, but specifications in successive arguments are catenated, 
pids List only the specified processes; they are comma-delimited. Thelistmust begiven 

immediately after the last option in a single command-line argument, with no intervening 
space, for example ps -j 1 , 4 , 5 . Lists specified in subsequent arguments are catenated, for 
example, ps - 11 , 23,4 5 6 will list all of the processes 1-6 in long format. 

LONG COMMAND-LINE OPTIONS 

T hese options are preceded by a double hyphen. 

- -sortx[+| - ] key [, C hoose a multi letter key from the sortkeys section. x may be any convenient separator 

l + 1 - 1 key [,...]] character. To beGNU-ish, use=. The + is really optional because default direction is 

increasing numerical or lexicographic order. Example: 

ps -jax -sort=uid,-ppid,+pid 

--help Get a help message that summarizes the usage and gives a list of supported sortkeys. This 

list may be more up-to-date than this man page 

SORTKEYS 

Note that the values used in sorting are the internal values ps uses and not the "cooked" values used in some of the output 
format fields If someone wants to volunteer to write special comparison functions for the cooked values,...;-) 


Short L ong 


cmdline 

flags 

pgr-p 

tpgld 


maj_flt 

cmin_flt 

cmaj_flt 


Description 

Simple name of executable 
Full command line 
Flags as in long format F field 
Process group ID 
Controlling tty process group ID 
Cumulative user time 
Cumulativesystem time 
User time 
System time 

N umber of minor page faults 
N umber of major page faults 
C umulative minor page faults 
C umulative major page faults 
Session ID 
Process ID 


continues 
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Short Long Desrription 


ppid 


tty 


priority 


Parent process ID 
Resident set size 
Resident pages 
Memory size in kilobytes 
Amount of shared pages 
The minor device number of tty 
Time process was started 
User ID number 
Username 

Total VM size in bytes 
Kernel scheduling priority 


FIELD DESCRIPTIONS 

pri Thisisthe counter field in thetask struct. It isthetimein hz of theprocess'spossibletimeslice 

ni Standard U NIX nicevalue; apositivevaluemeanslesscpu time 

size Virtual imagesize sizeof text+data+stack. 

rss Resident set size kilobytes of program in memory. 

wchan Name of the kernel function where the process is sleeping, with the sys stripped from the function name. If 
/boot/psdatabase does not exist, it isjust a hex number instead. 
stat Information about the status of the process The first field is r for runnable s for sleeping, Dfor uninterruptible 
sleep, t for stopped or traced, or z for a zombie process The second field contains w if the process has no resident 
pages The third field is n if the process has a positive nice value (ni field). 
tt Controlling tty. 

pagein N umber of major page faults (page faults that cause pages to be read from disk, including pages read from the 
buffer cache). 

trs Text resident size. 

swap Kilobytes (or pages if-p is used) on swap device 

share Shared memory. 


UPDATING 

This proc-based ps works by reading thefilesin theproc filesystem, mounted on /proc. Thisps does not need to besutd 
kmem or haveany privilegesto run. Donotgivethis ps anyspedalpermisaons 

You will need to update the /boot/psdatabase file by running /usr/sbin/psupdate to get meaningful information from the 
wchan field. This should be done every time you compileanew kernel. 

NOTES 

T he member used_math of task_struct is not shown, sincecrtB.s checksto seeif math ispresent. Thiscausesthemath flag 
to be sdt for all processes, and so it is worthless 

Programs swapped out to disk will be shown without command-line arguments and unless thee option is given, in 
parentheses. 

%cpu shows the cputim^realti me percentage. It will not add up to 100 percent unless you are lucky. It is time used divided 
by the time the process has been running. 

ThesizE and rss fields don't count the page tables and the task struct of a proc; this is at least 12k of memory that is 
always resident, size isthe virtual sizeof theproc (code+data+stack). 
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BUGS 

tty names are hard-coded: virtual consoles arevi, »2....; serial lines are s o and si; pty’sareppo, ppi ... p^|qi. 

AUTHORS 

ps was originally written by Branko Lankester (iankeste@fwi.uva.m) M ichael K. Johnson (johnsonm@sunsite.unc.edu) 
rewrote it significantly to use the proc filesystem, changing a few things in the process M ichael Shields 
(mjshieid@nyx.cs.du.edu) added the multiple -pids feature. Charles Blake(cbiake@ucsd.edu) added multilevel sorting and is 
the current maintaineroftheproc-ps suite 

Coheave Systems 21 July 1994 


psbb 

psbb— Extract bounding box from PostScript document 

SYNOPSIS 

DESCRIPTION 

psbb reads f i i e, which should be a PostScript document conforming to the document structuring conventions and looks for 
a %%BoundingBox comment. If it finds one, it prints a line 

llx lly urx ury 

on the standard output and exits with zero status If it doesn't find such a line or if the line is invalid, it prints a message and 
exits with nonzero status. 


SEE ALSO 

grops(l) 


GroffVersion 1.09, 6 August 1992 


psidtopgm 

psidtopgm— Convert PostScript image data into a portable graymap 

SYNOPSIS 

psidtopgm width height bits/sample [imagedata] 

DESCRIPTION 

psidtopgm reads the image data from a PostScript file as input and produces a portable graymap as output. 

This is a very simple and limited program, and is here only because so many people have asked for it. To use it you have to 
manually extract the readhexstring data portion from your PostScript file, and then give the width, height, and bit^sample 
on the command line. Before you attempt this, you should at least read the description of the image operator in thePostScript 
L anguage R eference M anual. 

It would probably not be too hard to write a script that uses thisfilter to read a specific variety of PostScript image but the 
variation is too great to make a general-purpose reader. Unless, of course you want to write a full-fledged PostScript 
interpreter... 

SEE ALSO 

pnmtops(l), pgm(5) 
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AUTHOR 

Copyright© 1989 byjef Poskanzer. 


2 August 1989 


pstopnm 

pstopnm— Convert a PostScript file into a portable anymap 

SYNOPSIS 

pstopnm [-forceplain][-help][-llx s][-lly s][-landscape][-portrait][-nocrop] 
[-pbm ]-pgm |-ppm][-urx s][-ury s][-verbose][-xborder n][-xmax n][-xsize f] 
[-yborder f ][-ymax n][-ysize n] psflie[.ps] 


DESCRIPTION 

pstopnm reads a PostScript file as input and produces portable anymap files as output. Thisprogram isjust a useful shell script 
that runs GhostScript to render a PostScript into one or morepnm files pstopnm will create as many files as the number of 
pages in the PostScript document. If the input file is named psftie.ps, the name of the files will be psfiieooi. ppm, 
psfiie 002 .ppm, and so on. 

T he program maps a rectangular portion of the PostScript document into an image file according to the command-line 
options The selected area will always be centered in the output file and may have borders around it. The image area to be 
extracted from the PostScript file and rendered into a portable anymap isdefined by four numbers the lower-left corner and 
the upper-right corner x and y coordinates. T hese coordinates are usually specified by the BoundingBox comment in the 
PostScript file header, but they can be overridden by the user by specifying one or more of the following flags -iix, -iiy, 
-urx, and -ury. The presence and thickness of a border to be left around the image area is controlled by the use of the flags 
-xborder and -yborder. If BoundingBox parameters are not found, and image area coordinates are not specified on the 
command line, default values are used. Unless both output file width and height are specified viathe-xsize and -ysize 
flags, the program will map the document into theoutput image by preserving its aspect ratio. 


OPTIONS 

-forceplain 


-llx bx 
-lly by 
-landscape 

-nocrop 

-pbm -pgm -ppm 


-verbose 
-xborder f rac 




Forces the output file to be a plain (in other words, not "raw") portable anymap. 

Prints the command syntax. 

Selects bx asthe lower left corner x coordinate (in inches). 

Selects by asthe lower left corner y coordinate (in inches). 

Renders the image in landscape mode 
Renders the image in portrait mode. 

Does not crop theoutput image dimensions to match the PostScript image area dimensions 
Selects the format of the output file. By default, all files are rendered as portable pixmaps (ppm format). 
Selectstx asthe upper-right corner x coordinate (in inches). 

Selectst y asthe upper-right corner y coordinate (in inches). 

Prints processing information to stdout. 

Specifies that the border width along theY axisshould be f r a c times the document width as specified by 
the bounding box comment in the PostScript file header. T he default value iso. i. 

Specifies that the maximum output image width should have a size less or equal to xs pixels (default: 612 ). 
Specifies that the output image width must be exactly xs pixels 

Specifies that the border width along the X axisshould bet r ac times the document width as specified by 
the bounding box comment in the PostScript file header. The default value iso. 1. 

Specifies that the maximum output image height should have a size less or equal toys pixels (default: 792 ). 
Specifies that the output image height must be exactly ys pixels. 
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BUGS 

The program will produce incorrect results with PostScript files that initializethecurrent transformation matrix. In these 
cases, page translation and rotation will not have any effect. To render these files, probably the best bet isto use the following 
flags: 

pstopnm -xborder 0 -yborder 0 -portrait -nocrop file.ps 

Additional flags may be needed if the document is supposed to be rendered on a medium different from letter-size paper. 

SEE ALSO 

gs(l), pstofits(l) 

COPYRIGHT 

Copyright© 1992 Smithsonian Astrophysical Observatory. PostScript is a trademark of Adobe Systems Inc. 

AUTHOR 

Alberto Accomazzi, WI PL, Center for Astrophysics 

28 D ecember 1992 


pstnee 

pstree- D isplay a tree of processes 

SYNOPSIS 

pstree [-a][-c][-h][-1][-p][-u][pi d| user ] 

DESCRIPTION 

pstree shows running processes as a tree. The tree is rooted at either ptd or tnit if pid is omitted. If a username is specified, 
all process trees rooted at processes owned by that user are shown. 

pstree visually merges identical branches by putting them in square brackets and prefixing them with the repetition count; 
for example, 

init-+-getty 
I -getty 
I-getty 
1 -getty 


becomes 


OPTIONS 

-a Show command-line arguments. Ifthecommand lineof a process is swapped out, that process is shown in 
parentheses -a implicitly disables compaction. 

-c Disable compaction of identical subtrees. By default, subtrees are compacted whenever possible. 

-h H ighlight the current process and its ancestors T his is a no-op if the terminal doesn't support highlighting or if 
neither the current process nor any of its ancestors are in the subtree being shown. 

-l Display long lines By default, lines are truncated to the display width or 132 if output is sent to a non-tty or if 
the display width is unknown. 

-p Show ptds. pidsareshown asdecimal numbersin parentheses after each processname. -p implicitly disables 
compaction. 

-u Show uid transitions W henever the uid of a process differs from theuid of its parent, the new uid is shown in 
parentheses after the process name 
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FILES 

/proc Location of the proc filesystem 

AUTHOR 

Werner Almesberger(aimesberMi.epfi.ch) 

SEE ALSO 

ps(l), top(l) 

Linux, 11 October 1994 


psupdate 

psupdate— U pdatethe ps database of kernel offsets 

SYNOPSIS 

psupdate [system path] 

DESCRIPTION 

psupdate updates the /boot/psdatabase file to correspond to the current kernel image system mapfile /usr/src/iinux/vmitnux 
by default. 

OPTIONS 

If your system mapfileisnot /usr/src/iinux/vmiinux, you may give the name of an alternate mapfile on the command line. 

FILES 

/boot/psdatabase 

/usr/src/linux/vmlin 

SEE ALSO 

ps(l), top(l), utmp(5) 

AUTHORS 

Original code written by Branko Lankaster, horribly munged by M ichael K. Johnson in a desperate effort to add /etc/ 
psdatabase support to procps. Someday, it should be rewritten, and the support in ps for alternate namelists added. Anyone 
want to volunteer to be added to the "Authors" section? 

Cohesive Systems 15 September 1993 


qrttoppm 

qrttoppm — Convert output from the Q RT ray tracer into a portable pixmap 

SYNOPSIS 

qrttoppm [ q r t fiI e ] 

DESCRIPTION 

qrttoppm readsaQRT file as input and produces a portable pixmap as output. 



ranlib 


SEE ALSO 

ppm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 




25Auguil989 


quota 

quota- D isplay disk usage and limits 

SYNOPSIS 

quota [ -guv | q ] 
quota [ -uv ! q ] user 
quota [ -gv | q ] group 

DESCRIPTION 

quota displays users' disk usage and limits By default, only the user quotas are printed. 

-g Print group quotas for the group of which the user is a member. The optional -u flag is equivalent to the default, 
-v Will display quotas on filesystems where no storage is allocated. 

-q Print a more terse message, containing only information on filesystems where usage is over quota. 

Specifying both -g and-u displays both the user quotas and the group quotas (for the user). 

Only the superuser may use the -u flag and the optional user argument to view thelimitsof other users Non-superusers can 
use the -g flag and optional group argument to view only the limits of groups of which they are members 
The-q flag takes precedence over the -v flag. 

quota reports the quotas of all the filesystems listed in /etc/tstab. For filesystems that are N FS-mounted, acall to the 
rpc.rquotad on the server machine is performed to get the information. If quota exits with a nonzero status, one or more 
filesystems are over quota. 

FILES 

quota.user Located at thefilesystem root with user quotas 

quota.group Located at the filesystem root with group quotas 

/etc/tstab To find filesystem namesand locations 

SEE ALSO 

quotactl(2), fstab(5), edquota(8), quotacheck(8), quotaon(8), repquota(8) 

8 January 1993 


ranlib 

raniib— Generate index to archive 

SYNOPSIS 

ranlib [ -v[-V] archi ve 
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DESCRIPTION 

raniib generates an index to the contents of an archive and stores it in thearchive The index lists each symbol defined by a 
member of an archive that is a relocatable object file. 

You may use ™ -sor™ --print-armap to listthisindex. 

An archive with such an index speeds up linking to thelibrary, and allows routines in thelibraryto call each other without 
regard to their placement in thearchive 

TheGNU raniib program is another form of G N U ar; running raniib is completely equivalent to executing ar -s. 

OPTIONS 

-v Print the version number of raniib and exit 

SEE ALSO 

binutiis entry in info ; TheGNU Binary Utilities, Roland H . Pesch (October 1991); ar(i); nm(i). 

COPYING 

Copyright© 1991 Free Software Foundation, Inc. Permission isgranted to make and distribute verbatim copies of this 
manual provided the copyright notice and this permission notice are preserved on all copies 
Permission isgranted to copy and distribute modified versions of this manual under the conditionsfor verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 
Permission isgranted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in theoriginal English. 

Cygnus support, 5 N ovemberl991 


rasttopnm 

rasttopnm— Convert a Sun raster file into a portable anymap 

SYNOPSIS 

rasttopnm [rastfiI e ] 

DESCRIPTION 

rasttopnm readsaSun raster file as input and produces a portable anymap as output. The type of the output file depends on 
the input file- if it's black and white, a pbm file iswritten; else if it's grayscale a pgm file; else a ppm file. The program tells you 
which type it is writing. 

SEE ALSO 

pnmtorast(l), pnm(5) 

AUTHOR 

Copyright© 1989,1991 byJefPodranzer. 

13 January 1991 
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rawtopgm 

nawtopgm- Convert raw grayscale bytes into a portablegraymap 

SYNOPSIS 

nawtopgm [-headenskip N][-rowskip N ] [-tb|-topbottom] [wi dt h height][imagedata] 

DESCRIPTION 

nawtopgm reads raw grayscale bytes asinput and produces a portable graymap as output. The input file is just grayscale bytes 
If you don't specify the width and height on the command line the program will check the size of the image and try to make 
a quadratic image of it. It is an error to supply a non-quadratic image without specifying width and height. The maxvai is 
assumed to be 255. 

OPTIONS 

-headenskip If the file has a header, you can usethisflagto skip over it. 

-nowskip If there is padding at the ends of the rows you can skip it with thisflag. Note that nowskip can be a real 

number. Amazingly, I once had an image with 0.376 bytes of padding per row. Thisturned out to be due 
to afile transfer problem, but I was still able to read theimage. 

-tb -topbottom Flips the image upside down. Thefirst pixel in a pgm file is in the lower-left corner of the image For 

conversion from images with thefirst pixel in the upper-left corner (for example the M olecular D ynamics 
and Leica confocal formats), thisflips the image right. This isequivalent to nawtopgm [file] | pnmfiip 
-tb. 

BUGS 

If you don't specify the image width and height, the program will try to read theentire image to a memory buffer. If you get 
a message that states that you are out of memory, try to specify the width and height on the command line Also, the -tb 
option consumes much memory. 

SEE ALSO 

pgm(5), nawtoppm(l), pnmflip(l) 

AUTHORS 

Copyright© 1989 byjef Poskanzer; modified June 1993 by 0 liver Trepte(oiiven@fysik4. kth.se). 

15Junel993 


rawtoppm 

nawtoppm— Convert raw RGB bytes into a portable pixmap 

SYNOPSIS 

nawtoppm[-headenskip N][-nowskip N][-ngbj-nbgj-gnb |-gbn]-bng|-bgn ] 

[-intenpixel]-intennow] width height [imagedata] 

DESCRIPTION 

nawtoppm reads raw RG B bytes asinput and produces a portable pixmap asoutput. T heinput file isjust RG B bytes. You have 
to specify the width and height on the command line because the program obviously can't get them from the file. The maxvai 
is assumed to be 255. If the resulting image is upside down, run it through pnmfiip -tb. 
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OPTIONS 

-headerskip If the file has a header, you can usethisflagto ski p over i t. 

-rowskip If there is padding at the ends of the rows, you can skip it with thisflag. 

-rgb -rbg -grb -gbr -brg -bgr Theseflags let you specify alternate color orders. Thedefault is -rgb. 

-interpixei -interrow These flags let you specify how the colors are interleaved. Thedefault is -tnterpixei, 

meaning interleaved by pixel. A byte of red, a byte of green, and a byte of blue or whatever 
color order you specified, -interrow means interleaved by row- a row of red, a row of 
green, a row of blue assuming standard RG B color order. An -interpiane flag- all the red 
pixels, then all the green, then all the blue- would be an obvious extension, but is not 
implemented. You could get thesame effect by splitting thefile into three parts (perhaps 
using dd), turning each part into a PGM file with rawtopgm, and then combining them with 

rgb3toppm. 


SEE ALSO 

ppm(5), rawtopgm(l), rgb3toppm(l), pnmflip(l) 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

6 February 1991 


rep 

rep- Remote file copy 

SYNOPSIS 

rep [-px] [-k realm] fiI el fiI e2 

rep [-px] [-r] [-k Ar realm] file ... directory 

DESCRIPTION 

rep copies files between machines. Each file or directory argument iseither a remote filename of theform rname@rhost:path, 
or a local filename (containing no : characters or a / before any : characters). 

-r If any of the source files are directories rep copies each subtree rooted at that name; in this case the destination 
must be a directory. 

-p C auses rep to attempt to preserve (duplicate) in its copies the modification times and modes of the source files 
ignoring the umask . By default, the mode and owner of f i i e 2 are preserved if it already existed; otherwise, the 
modeof the source file modified by the umask 2 on the destination hostisused. 

-k Requests rep to obtain tickets for the remote host in realm real m instead of the remote host's realm as determined 
by krb_realmofhost 3. 

-x Turnson DESencryption for all data passed by rep. Thismay impact response time and CPU utilization, but 
provides increased security. 

If path is not a full pathname it is interpreted relative to the login directory of the specified user ruser on rhost, or your 
current username if no other remote username isspecified. A path on a remote host may be quoted (using \,", or') so that 
the meta characters are interpreted remotely. 

rep does not prompt for passwords; it performs remote execution via rsh(l), and requires the same authorization, 
rep handles third-party copies, where neither source nor target files are on the current machine. 



SEE ALSO 

cp(l), ftp(l), rsh(l), rlogin(l) 

HISTORY 

The rep command appeared in BSD 4.2 . The version of rep described here has been reimplemented with Kerberosin BSD 
4.3 Reno. 

BUGS 

Doesn't detect all cases in which the target of a copy might be a file when only a directory should be legal. 

Is confused by any output generated by commands in a or file on the remote host. 

The destination username and hostname may have to be specified asrhost.rname when the destination machine is running 
the BSD 4.2 version of rep. 

BSD 4.3r, 27July 1991 


rcs 

res- C hange RC S file attributes 

SYNOPSIS 

DESCRIPTION 

res creates new RC S files or changes attributes of existing ones An RC S file contains multiple revisions of text, an access list, 
a change log, descriptive text, and some control attributes For res to work, the caller's login name must be on theaccess 
list- unless the access list is empty, the caller is the owner of thefile or the superuser, or the -i option is present. 
Pathnamesmatchingan RCS suffix denote RCS files' all others denote working files. N ames are paired as explained in ci(l). 
Revision numbersusethesyntaxdescribed in ci(l). 

OPTIONS 

-i Create and initialize a new RCS file, but do not deposit any revision. If the RCS file has no path prefix, try 

to place it first into the subdirectory . / rcs, and then into the current directory. If the RC S file already 
exists, print an error message 

-ai ogi ns Append the login namesappearing in the comma-separated list i ogi ns to the access list of the RCS file 

-Aoidfiie Append the access list of oi dm e to the access list of the RCS file. 

-e[i ogi ns ] Erase the login namesappearing in the comma-separated list i ogi ns from the access list of the RCS file If 
i ogi ns isomitted, erasethe entire access list. 

-b [ r e v ] Set the default branch to rev.If rev is omitted, the default branch is reset to the (dynamically) highest 

branch on the trunk. 

-cstring Set thecomment leaderto st r i ng. An initial ci,or an rcs -i without -c, guessesthecommentleaderfrom 

the suffix of the working filename. 

This option is obsolescent, since RCS normally uses the preceding $Log$ line's prefix when inserting log lines during 
checkout (see co(l)). FI owever, older versionsof RC S use the comment leader i nstead of the $Log$ line's prefix, so if you plan 
to access a file with both old and new versionsof RCS, make sure its comment leader matches its $Log$ line prefix. 

-ksubst Set the default keyword substitution to subst .The effect of keyword substitution is described in co(l). 

Giving an explicit -k option to co, resdiff, and resmerge overrides this default. Beware rcs -kv, because 
-kv is incompatible with co -i. Use rcs -kkv to restorethe normal default keyword substitution. 
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-nname [: [r ev ] ] 


-Nn a me [: [r e v ]] 


-orange 


Lock the revision with number rev. If a branch isgiven, lock the latest revision on that branch. If rev is 
omitted, lock the latest revision on the default branch. Locking prevents overlapping changes. If someone 
else already holds the lock, the lock is broken as with res -u. 

Unlock the revision with number rev. If a branch isgiven, unlock the latest revision on that branch. If rev 
is omitted, remove the latest lock held by the caller. Normally, only the locker of a revision can unlock it. 
Somebody else unlocking a revision breaks the lock. This causes a mail message to be sent to the original 
locker. The message contains a commentary solicited from the breaker. Thecommentary isterminated by 
end-of-file or by a line containing a period by itself. 

Set locking to strict, strict locking meansthat the owner of an RCS file is not exempt from locking for 
checkin. This option should be used for files that are shared. 

Set locking to non-strict. non-strict locking meansthat the owner of a file need not lock a revision for 
checkin. This option should not be used for files that are shared. Whether default locking is strict is 
determined by your system administrator, but it is normally strict. 

Replace revision rev 'slog message with msg. 

Do not send mail when breaking somebody else’s lock. Thisoption is not meant for casual use; itismeant 
for programsthat warn users by other means, and invoke res -u only as a low-level lock-breaking 
operation. 

Associate the symbolic narnename with the branch or revision rev. Deldte the symbolic name if both : and 
rev are omitted; otherwise, print an error message if name is already associated with another number. If rev 
is symbolic, it isexpanded before association. A rev consisting of a branch number followed by a period 
stands for the current latest revision in the branch. A : with an empty rev stands for the current latest 
revision on the default branch, normally the trunk. For example, res -nname: rcs /* associates name with 
the current latest revision of all the named RC S files; this contrasts with rcs -nname:$ rcs/*, which 
associates name with the revision numbers extracted from keyword strings in thecorresponding working 
files 

Act like -n, except override any previous assignment of name . 

Deletes ("outdates") the revisions given by range. A range consisting of a single revision number means 
that revision. A range consisting of a branch number means the latest revision on that branch. A range of 
theform revi: rev 2 means revisionsr evi to r e v 2 on thesame branch, :rev meansfrom the beginning of 
the branch containing rev up to and including rev, and rev : meansfrom revision rev to the end of the 
branch containing r ev . N one of the outdated revisionscan have branches or locks 
Run quietly; do not print diagnostics. 

Run interactively, even if the standard input is not a terminal. 

Set the state attribute of the revision r ev to state. If rev is a branch number, assume the latest revision on 
that branch. If rev is omitted, assume the latest revision on the default branch. Any identifier is acceptable 
for st at e . A useful set of states isExp (for experimental), stab (for stable), and Rei (for released). By 
default, ci(l) sets the state of a revision to Exp. 

W rite descriptive text from thecontents of the named file into the RC S file, deleting the existing text. 
Thef i 1 e pathnamecannot begin with -. If f i 1 e is omitted, obtain thetext from standard input, 
terminated by end-of-file or by a line containing a period by itself. Prompt for the text if interaction is 
possible; see-1. With -i, descriptive text is obtained even if -t is not given. 

W rite descriptive text from thest ring into the RCS file, deleting the existing text. 

Preserve the modification timeon the RCS file unless a revision is removed. Thisoption can suppress 
extensive recompilation caused by a make(l) dependency of some copy of the working file on the RC S file. 
Use this option with care; it can suppress recompilation even when it is needed, that is, when a change to 
the RCS file would mean a change to keyword strings in the working file. 

Print RCS’s version number. 

Emulate RCS version n. See co(l) for details 

Usesuf f i xes to characterize RCS files See ci(l) for details. 

U se z 0 n e as the default ti me zone T his option has no effect; it is present for compati bility with other RC S 
commands 



At least one explicit option must be given, to ensure compatibility with future planned extensionsto the res command. 

COMPATIBILITY 

The-brev option generates an RCS file that cannot be parsed by RCS version 3 or earlier. 

The-ksubst options (except -kkv) generate an RCS file that cannot be parsed by RCS version 4 or earlier. 

Use res -vn to make an RCS file acceptable to RCS version n by discarding information that would confuse version n. 

RCS version 5.5 and earlier does not support the-x option, and requires a ,v suffix on an RCS pathname. 

FILES 

res accesses files much asci(l)does, except that it uses the effective user for all accesses, it does not write the working file or 
its directory, and it does not even read the working file unless a revision number of$ is specified. 

ENVIRONMENT 

RCSiNiTt i [: r e v ] 0 ptions prepended to the argument list, separated by spaces. See ci(l) for details 

DIAGNOSTICS 

The RCS pathname and the revisions outdated are written to the diagnostic output. The exit status is zero if and only if all 
operations were successful. 

IDENTIFICATION 

Author: Walter F.Tichy. 

M anual Page Revision: 5.13; Release D ate: 1995/06/05. 

Copyright 1982,1988,1989 W alter F. Tichy. 

Copyright 1990,1991,1992,1993,1994,1995 Paul Eggert. 

SEE ALSO 

rcsintro(l), co(l), ci(l), ident(l), rcsclean(l), resdiff(1), rcsmerge(l), rlog(l), rcsfile(5) 

"RCS—A System for Version Control" by W alter F. Tichy, software Practice & Experience 15, 7 (July 1985), pages 
637-654. 

BUGS 

A catastrophe (for example, asystem crash) can causeRCSto leave behind asemaphore file that causes later invocations of 
RCS to claim that the RCS file is in use To fix this, remove the semaphore file A semaphore file's name typically begins 
with a comma or ends with an underscore 

Theseparator for revision rangesin the -o option used to be - instead of:, but this leads to confusion when symbolic names 
contain -. For backwards compatibility, res -o still supports the old - separator, but it warns about this obsolete use. 
Symbolic names need not refer to existing revisions or branches For example, the -o option does not remove symbolic names 
for the outdated revisions you must use -n to remove the names 

GNU, 5 Junel995 


rcsclean 

rcsciean— Clean up working files 


SYNOPSIS 
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DESCRIPTION 

rcsciean removes files that are not being worked on.rcsciean -u also unlocks and removes files that are being worked on 
but have not changed. 

For each f i i e given, rcsciean comparesthe working file and a revision in the corresponding RCS file If it finds a difference, 
it does nothing. Otherwise, it first unlocks the revision if the -u option isgiven, and then removes theworking file unless the 
working file is writable and the revision is locked. It logs its actions by outputting the corresponding res -u and ™ -f 
commandson the standard output. 

Files are paired asexplained in ci(l). If no f i i e isgiven, all working files in the current directory are cleaned. Pathnames 
matching an RCS suffix denote RCS files; all others denote working files. 

The number of the revision to which the working file is compared may be attached to any of the options-n, -q, -r, or-u. If 
no revision number is specified, then if the-u option isgiven and the caller has one revision locked, rcsciean uses that 
revision; otherwise, rcsciean uses the latest revision on the default branch, normally the root, 
rcsciean isuseful for clean targets in makefiles See also rcsdiff(l), which prints out the differences and ci(l), which 
normally reverts to the previous revision if a file was not changed. 

OPTIONS 

-ksubst Usesubst -style keyword substitution when retrieving the revision for comparison. Seeco(l) for details. 

-n [rev ] D o not actually remove any filesor unlock any revisions Using this option will tell you what rcsciean 

would do without actual ly doing it. 

--q[rev] Do notlogtheactionstaken on standard output. 

--r[rev] Thisoption has no effect other than specifying the revision for comparison. 

-t Preserve the modification time on the RC S file even if the RC S file changes because a lock is removed. 

Thisoption can suppress extensive recompilation caused by amake(l) dependency of some other copy of 
the working file on the RCS file. Use this option with care; it can suppress recompilation even when it is 
needed, that is, when the lock removal would mean a change to keyword strings in the other working file 
-u [r e v ] Unlock the revision if itislocked and no difference is found. 

-v Print RCS's version number. 

-vn Emulate RCS version n. Seeco(l) for details 

-xsuf f i xes Usesuf f i xes to characterize RCS files Seeci(l) for details. 

-zzone Usezone asthetimezonefor keyword substitution; see co(l) for details 

EXAMPLES 

rcsciean *.c *.h removesall workingfilesending in .c or.h that were not changed sincetheir checkout, 
rcsciean removesall working files in the current directory that were not changed sincetheir check-out. 

FILES 

rcsciean accesses files much asci(l) does. 

ENVIRONMENT 

rcsinit Options prepended to the argument list, separated by spaces. A backslash escapes spaces within an option. The 
rcsinit options are prepended to the argument lists of most res commands. U seful rcsinit optionsindude-q, 
-v, -x, and -z. 


DIAGNOSTICS 

The exit status is zero if and only if all operations were successful. M issing working files and RCS files are silently ignored. 



IDENTIFICATION 

Author: Walter F.Tichy. 

M anual Page Revision: 1.12; Release Date: 1993/11/03. 

Copyright© 1982,1988,1989 Walter F. Tichy. 

Copyright© 1990,1991,1992,1993 Paul Eggert. 

SEE ALSO 

ci( 1 ), co( 1 ), ident(l), rcs(l), rcsdiff(l), rcsintro(l), rcsmerge(l), rlog(l), rcsfile( 5 ) 

"RCS-A System forVersion Control" by Walter F. Tichy, software Practice & Experience 15, 7 (July 1985), pages 
637-654. 

BUGS 

At least onef i i e must be given in older UN IX versionsthat do not provide the needed directory scanning operations 

GNU, 3 November 1993 


rcsdiff 

rcsdiff — Compare res revisions 

SYNOPSIS 

rcsdiff [ -ksubst ][-q ][-rrevl [ -rrev 2 ]][-T ][-V[n]][-xsuffixes ][-zzone ] 

[d i f f options ] fiIe . . . 

DESCRIPTION 

rcsdiff runsdiff(l) to compare two revisions of each RCS filegiven. 

Pathnamesmatchingan rcs suffix denote RCS files; all othersdenote working files. N ames are paired as explained in ci(l). 
Theoption -q suppresses diagnostic output. Zero, one, or two revisions may be specified with -r.Theoption -ksubst affects 
keyword substitution when extracting revisions, asdescribed in co(l); for example, -kk -ri.i -ri .2 ignores differences in 
keyword values when comparing revisions 1.1 and 1.2. To avoid excess output from locker name substitution, -kkvi is 
assumed if at most one revision option isgiven, no -k option isgiven, -kkv isthedefault keyword substitution, and the 
working file’s mode would be produced by co -1. Seeco(l) for details about -t, -v, -x, and -z. Otherwise, all optionsof 
diff(l) that apply to regular files are accepted, with the same meaning asfordiff. 

If both r ev 1 and re»2 are omitted, rcsdiff compares the latest revision on the default branch (by default the trunk) with the 
contents of the corresponding working file. This is useful for determining what you changed since the last checkin. 

If r ev 1 isgiven, but rev2 isomitted, rcsdiff compares revision rev 1 of the RCS file with the contents of the corresponding 
working file. 

If both r ev 1 andrev2 are given, rcsdiff compares revisions revi and r ev2 of the RCS file. 

Both r ev 1 andrev 2 may be given numerically or symbolically. 

EXAMPLE 

The command 

rcsdiff f.c 

compares the latest revision on the default branch of the RC S file to the contents of the working filef.c. 

ENVIRONMENT 

rcsinit Options prepended to theargument list, separated by spaces. See ci(l) for details 
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DIAGNOSTICS 

Exit status is 0 for no differences during any comparison, i for some differences, 2 for trouble. 

IDENTIFICATION 

Author: Walter F.Tichy. 

M anual Page Revision: 5.5; Release D ate: 1993/11/03. 

Copyright© 1982,1988,1989 Walter F. Tichy. 

Copyright© 1990,1991,1992,1993 Paul Eggert. 

SEE ALSO 

ci( 1), co(l), diff(l), ident(l), rcs(l), rcsintro(l), rcsmerge(l), rlog(l) 

"RCS-A System forVersion Control" by Walter F. Tichy, software Practice & Experience 15, 7 (July 1985), pages 
637-654. 

GNU, 3 November 1993 


rcsfreeze 

rcsfreeze— Freeze a configuration of sources checked in under RCS 

SYNOPSIS 

rcsfreeze [name] 

DESCRIPTION 

rcsfreeze assigns a symbolic revision number to a sdt of RCS files that form a valid configuration. 

The idea isto run rcsfreeze each time a new version is checked in. A unique symbolic narne(c_number, where number is 
increased each time rcsfreeze is run) isthen assigned to the most recent revision of each RCS file of the main trunk. 

An optional name argumentto rcsfreeze gives a symbolic name to the configuration. Theunique identifier isstill generated 
and is listed in the log file, but it will not appear as part of the symbolic revision name in theactual RCS files 
A log message is requested from the user for future reference. 

The shell script works only on all RCS files at onetime. All changed files must be checked in already. Run rcsciean(l) first 
and see whether any sources remain in the current directory. 

FILES 

rcs/. rcsfreeze.ver Version number 

rcs/. rcsfreeze. log Log messages most recent first 

AUTHOR 

Stephan V. Bechtolsheim 

SEE ALSO 

co(1), rcs(l), rcsclean(l), rlog(l) 

BUGS 

rcsfreeze does not check whether any sources are checked out and modified. 

Although both source filenames and RCS filenames are accepted, they are not paired as usual with rcs commands 
Error checking is rudimentary. 



rdntro 




rcsfreeze isjust an optional example shell script, and should not betaken too seriously. See cvs for a more complete 
solution. 

GNU, 3 November 1990 


rcsintro 

ncsintro— Introduction to res commands 

DESCRIPTION 

The Revision Control System (RCS) manages multiple revisions of files. RCS automates the storing, retrieval, logging, 
identification, and merging of revisions. RCS is useful for text that is revised frequently; for example programs, documenta¬ 
tion, graphics, papers, and form letters 

The basic user interface is extremely simple. The novice only needs to learn two commands: ci(l) and co(l). ci, short for 
check in, deposits the contents of a file into an archival file called an RCS file. An RCS file contains all revisionsof a 
particular file co, short for check out, retrieves revisions from an RCS file. 

FUNCTIONSOF RCS 

Store and retrieve multiple revisions of text. RCSsavesall old revisions in a space-efficient way. Changes no longer destroy 
the original because the previous revisions remain accessible Revisionscan be retrieved according to ranges of revision 
numbers, symbolic names, dates, authors, and states 

Maintain a complete history of changes RCS logs all changes automatically. Besides thetext of each revision, RCSstores 
the author, the date and time of checkin, and a log message summarizing the change The logging makes it easy to find out 
what happened to a module without having to compare source listings or having to track down colleagues. 

Resolve access conflicts When two or more programmers wish to modify the same revision, RCS alerts the programmers 
and prevents one modification from corrupting the other. 

Maintain a tree of revisions RCScan maintain separate lines of development for each module. It stores a tree structure that 
represents the ancestral relationships among revisions. 

Merge revisions and resolve conflicts Two separate lines of development of a module can be coalesced by merging. If the 
revisions to be merged affect the samesections of code RCS alerts the user about the overlapping changes. 

Control releases and configurations Revisionscan be assigned symbolic names and marked as released, stable, experimen¬ 
tal, and so on. With these facilities configurations of modules can be described simply and directly. 

Automatically identify each revision with name, revision number, creation time, author, and so on. The identification 
is like a stamp that can be embedded at an appropriate place in the text of a revision. T he identification makes it simple to 
determine which revisionsof which modules make up a given configuration. 

M inimize secondary storage RCS needs little extra space for the revisions (only the differences). If intermediate revisions 
are deleted, the corresponding deltas are compressed accordingly. 

GETTING STARTED WITH RCS 

Suppose you have a file f.c that you wish to put under control of RCS. If you have not already done so, make an rcs 
directory with the command: 

mkdir RCS 

Then invoke the check in command: 


This command creates an RCS file in the rcs directory, stores f .c into it as revision 1.1, and deletes f.c. It also asks you for 
a description. The description should be a synopsis of the contents of thefile. All later check in commands will ask you for a 
log entry, which should summarize the changes that you made. 
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Files in theRCs directory are called RCS files; the others are called working files To get back the working filet, c in the 
previous example, use the check out command: 


This command extracts the latest revision from theRCS file and writes it into t .c. If you want to edit t .c, you must lock it 
as you check it out with the command: 


You can now edit t.c. 

Suppose after some editing you want to know what changes that you have made The command: 

rcsdiff f.c 

tells you the difference between the most recently checked-in version and the working file. You can check thefile back in by 
invoking 


This increments the revision number properly. 

If ci complains with the message: 

ci error: no lock set by your name 

then you have tried to check in a file even though you did not lock it when you checked it out. Of course it istoo late now 
to do the checkout with locking, because another checkout would overwrite your modifications. Instead, invoke 


This command will lock the latest revision for you, unless somebody else got ahead of you already. In that case, you'll have to 
negotiate with that person. 

Locking assures that you, and only you, can check in the next update and avoids nasty problems if several people work on 
the same file. Even if a revision is locked, it can still be checked out for reading, compiling, and soon. All that locking 
prevents is a check-in by anybody but the locker. 

If your RCS file is private-if you are the only person who is going to deposit revisions into it— strict locking is not needed 
and you can turn it off. If strict locking isturned off, the owner of the RCS file need not have a lock for checkin; all others 
still do. Turning strict locking off and on is done with the commands res -u f.c and res -l f.c. If you don't want to 
clutter your working directory with RC S files, create a subdirectory called rcs in your working directory, and move all your 
RCS files there rcs commands will look first into that directory to find needed files All the commands discussed here will 
still work, without any modification. (Actually, pairs of RCS and working files can be specified in three ways both are given, 
only the working file is given, or only the RCS file is given. Both RCS and working files may have arbitrary path prefixes rcs 
commands pair them up intelligently.) 

To avoid the deletion of the working file during checkin (in case you want to continue editing or compiling), invoke 


These commands check in f.c as usual, but perform an implicit checkout. Thefirst form also locks the checked in revision, 
the second one doesn't. Thus these options save you one checkout operation. Thefirst form is useful if you want to 
continue editing, the second one if you just want to read thefile. Both update the identification markers in your working 
file. (See the following subsection, "Automatic Identification.") 

You can giveci the number you want assigned to a checked in revision. Assume all your revisions were numbered 1.1,1.2, 
1.3, etc., and you would like to start release 2. The command: 

ci -r2 f.c or ci -r2.1 f.c 


assigns the number 2.1 to the new revision. From then on, ci will number thesubsequent revisions with 2.2,2.3, and so on. 
The corresponding co commands: 
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co -r2 f.c 

and 


retrieve the latest revision numbered 2.x and thera/ision 2.1, respectively, co without a revision number selects the latest 
revision on the trunk, that is, the highest revision with a number consisting of two fields N umbers with more than two 
fields are needed for branches. For example to start a branch at revision 1.3, invoke 


This command starts a branch numbered 1 at revision 1.3, and assigns the number 1.3.1.1 to the new revision. For more 
information about branches, see rcsfiie(5). 

AUTOMATIC IDENTIFICATION 

RCScan put special strings for identification into your source and object code To obtain such identification, place the 
marker: 

$Id$ 

into your text, for instance inside a comment. RC Swill replace this marker with a string of theform: 

$Id: f i I ename revi si on date t i me author state $ 

With such a marker on the first page of each module you can always see with which revision you are working. RCS keeps 
the markers up-to-date automatically. To propagate the markers into your object code, simply put them into literal character 
strings. In C, thisisdoneasfollows: 

The command ident extracts such markers from any file even object code and dumps. Thus, ident lets you find out which 
revisions of which modules were used in a given program. 

You may also find it useful to put the marker $Log$ into your text, inside a comment. This marker accumulates the log 
messages that are requested during checkin. Thus, you can maintain the complete history of your file directly inside it. There 
are several additional identification markers see co(l) for details 

IDENTIFICATION 

Author: Walter F.Tichy. 

M anual Page Revision: 5.3; Release D ate: 1993/11/03. 

Copyright© 1982,1988,1989 Walter F. Tichy. 

Copyright© 1990,1991,1992,1993 Paul Eggert. 

SEE ALSO 

ci( 1), co(1), ident(l), rcs(l), rcsdiff(l), rcsintro(l), rcsmerge(l), rlog(l) 

"RCS-A System forVersion Control" by Walter F. Tichy, software Practice & Experience 15, 7 (July 1985), pages 
637-654. 

GNU, 3 November 1993 


rcsmerge 

rcsmerge— M erge RCS revisions 

SYNOPSIS 

rcsmerge [options] file 
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DESCRIPTION 

rcsmerge incorporates the changes between two revisionsof an RCS file into the corresponding working file. 

Pathnames matching an rcs suffix denote RCS files; all others denote working files. N ames are paired as explained in ci(l). 
At least one revision must be specified with one of the options described in the next subsection, usually -r. At most two 
revisions may be specified. If only one revision is specified, the latest revision on the default branch (normally the highest 
branch on the trunk) is assumed for the second revision. Revisions may be specified numerically or symbolically, 
rcsmerge prints a warning if there are overlaps, and delimits the overlapping regions asexplained in merge(l). The command 
is useful for incorporating changesinto a checked-out revision. 

OPTIONS 


-p[r ev ] 
-q [rev] 
-r[rev] 


EXAMPLES 

Suppose you have released revision 2.8off.c. Assume, furthermore that after you complete an unreleased revision 3.4, you 
receive updates to release 2.8 from someone else. T o combine the updates to 2.8 and your changes between 2.8 and 3.4, put 
theupdatesto 2.8 into filet.c and execute 

rcsmerge -p -r2.8 -r3.4 f.c >f.merged.c 

Then examine f. merged, c. Alternatively, if you want to save the updates to 2.8 in the RCS file, check them in as revision 
2.8.1.1 and execute co -j: 
ci -r2.8.1.1 f.c 
CO -r3.4 -j2.8:2.8.1.1 f.c 

As another example, the following command undoes the changes between revision 2.4 and 2.8 in your currently checked out 
revision in f.c: 

rcsmerge -r2.8 -r2.4 f.c 

Note the order of the arguments, andthatf.c will be overwritten. 

ENVIRONMENT 

rcsinit 0 ptions prepended to the argument list, separated by spaces. See ci(l) for details 

DIAGNOSTICS 

Exit status iso for no overlaps i for some overlaps, 2 for trouble. 


Output conflicts using the -a style of diff3(l), if supported by diff3. This merges all changes leading 
fromfiie2 to fiie3 into fiiei, and generates the most verbose output. 

T hese options specify conflict styles that generate less information than -a. See diff3(l) for detai Is. T he 
default is -e. With-e, rcsmerge does not warn about conflicts. 

Use sub st -style keyword substitution. See co(l) for details. For example -kk -n.i -ri .2 ignores 
differences in keyword values when merging the changes from 1.1 to 1.2. It normally does not make sense 
to merge binary files as if they were text, so rcsmerge refuses to mergefiles if -kb expansion is used. 

Send the result to standard output instead of overwriting the working file. 

Run quietly; do not print diagnostics. 

Merge with respect to revision rev. Here an empty rev stands for the latest revision on the default branch, 
normally the head. 

This option has no effect; it is present for compatibility with other rcs commands 
Print RCS's version number. 

Emulate RCS version n. See co(l) for details 

Uses uf f i xes to characterize RCS files See ci(l) for details. 

Use zone as the time zone for keyword substitution. Seeco(l) for details. 




IDENTIFICATION 

Author: Walter F.Tichy. 

M anual Page Revision: 5.6; Release D ate: 1995/06/01. 

Copyright© 1982,1988,1989 Walter F. Tichy. 

Copyright© 1990,1991,1992,1993,1994,1995 Paul Eggert. 

SEE ALSO 

ci( 1), co(1), ident(l), merge(l), rcs(l), rcsdiff(l), rcsintro(l), rlog(l), rcsfile(5) 

"RCS—A System for Version Control" by Walter F. Tichy, Software-Practice & Experience 15, 7 (July 1985), pages 
637-654. 

GNU, 1 Junel995 


rdist 

rdist — Remote file distribution program 

SYNOPSIS 

rdist [-nqbRhivwy] [ f distfiie] [-d var =value ] [-m host ] [name ...] 
rdist [-nqbRhivwy] -c name ... [login@host:dest] 

DESCRIPTION 

rdist isa program to maintain identical copies of files over multiple hosts. It preserves the owner, group, mode, and mtime 
of files if possible and can update programs that are executing, rdist reads commands from distfiie to direct the updating 
of files and/or directories. 

Options specific to the first synopsis form: 

If distfiie is-, the standard input is used. 

-f distfiie Use the specified distfiie. 

If either the -f or - option is not specified, the program looksfirst for distfiie, then Distfiie to use as the input. If no 
names are specified on the command line rdist will update all ofthefilesand directories listed in distfiie. Otherwise, the 
argument is taken to be the name of a file to be updated or the label of a command to execute. If label and filenames conflict, 
itisassumed to be a label. These may be used together to update specific files using specific commands 
0 ptions specific to the second synopsis form: 

-c Forces rdist to interpret the remaining arguments as a small distfiie. 

The equivalent distfiie is as follows 
name ... -i login® host install dest ; 

0 ptions common to both forms: 

-b Binary comparison. Perform a binary comparison and update files if they differ rather than comparing 

dates and sizes 

-d v ar =va i ue D efi ne v a r to havevai ue. The -d option isused to define or override variable definitions in the distfiie. 

value can be the empty string, one name, or a list of names surrounded by parentheses and separated by 
tabs and/or spaces 

-h Follow symbolic links Copy thefile that the link points to rather than the link itself. 

-i Ignore unresolved links rdist will normally try to maintain the link structure of files being transferred and 

warn the user if all the links cannot be found. 

-m host Limitwhich machinesareto beupdated. M ultiple -m arguments can be given to limit updates to a subset 

of the hosts listed in the distfiie. 
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-n Print the commands without executing them. Thisoption is useful for debugging distfiie. 

-q Quiet mode. Files that are being modified are normally printed on standard output. The -q option 

suppresses this 

-R Removeextraneousfiles If a directory is being updated, any filesthat exist on the remote host that do not 

exist in themasterdirectory are removed. This isuseful for maintaining truly identical copies of directo¬ 
ries. 

-v Verify thatthefiles are up-to-dateon all the hosts. Anyfiles that are out-of-date will be displayed, but no 

files will be changed nor any mail sent. 

-w Whole mode Thewholefilenameisappended to the destination directory name. Normally, only the last 

component of a name is used when renaming files. Thiswill preserve the directory structure of thefiles 
being copied instead of flattening the directory structure. For example, renaming a list of files such as 
dirl/fl dir2/f2 to dir3 would Create files dir3/dir1/f1 and dir3/dir2/f2 instead of dir3/f1 and dir3/f2. 

-y Younger mode Files are normally updated if their mtime and size (see stat(2)for more details) disagree. 

The -y option causes rdist not to update files that are younger than the master copy. Thiscan be used to 
prevent newer copieson other hosts from being replaced. A warning message is printed for filesthat are 
newer than the master copy. 

distfiie contains a sequence of entries that specify thefiles to be copied, the destination hosts, and whatoperationsto 
perform to do the updating. Each entry hasone of the following formats 

<variable name>'=' <name list> 

[label: ]<source list> destination listxcommand list> 

[label: ]<source list> ':: 1 <time_stamp filexcommand list> 

Thefirst format is used for defining variables The second format is used for distributing files to other hosts. The third 
format is used for making lists of filesthat have been changed since some given date. Thesource list specifies a list of files 
and/or directories on the local host that are to be used as the master copy for distribution. T he destination list isthe list of 
hosts to which these files are to be copied. Each file in the source list is added to a list of changes if the file is out-of-date on 
the host that is being updated (second format), or the fi le is newer than the timestamp file (third format). 

Labels are optional. They are used to identify a command for partial updates. 

Newlines, tabs, and blanks are only used as separators and are otherwise ignored. Comments begin with # and end with a 
newline 

Variables to be expanded begin with $ followed by one character or a name enclosed in curly braces (see the examples at the 
end). 

Thesourceand destination listshavethefollowingformat: <name> or '(' <zero or more names separated by white-space> 

The shell metacharacters!, [,{,}, *, and ? are recognized and expanded (on the local host only) in the same way ascsh(l). 
They can be escaped with a backslash. The - character is also expanded in the same way ascsh(l) but is expanded separately 
on the local and destination hosts. When the -w option is used with a filename that begins with \ everything except the 
homedirectory isappended to the destination name. Filenames that do not begin with / or - use the destination user's home 
directory as the root di rectory for the rest of the fi lename. 

T he command list consists of zero or more commands of the following format: 

'install' <options> opt_dest_name ';' 

'notify' <name list> ';' 

'except' <name list> ';' 

'except_pat' <pattern list> 

'special' <name list> string ';' 

The install command is used to copy out-of-date files and/or directories Each sourcefile iscopied to each host in the 
destination list. D irectories are recursively copied in the same way. opt_dest_name is an optional parameter to renamefiles. If 
no install command appears in the command list or the destination name is not specified, the source filename is used. 
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D irectories in the pathname will be created if they do not exist on the remote host. To help prevent disasters, a nonempty 
directory on a target host will never be replaced with a regular file or a symbolic link. However, under the -r option, a 
nonempty directory will be removed if the corresponding filename is completely absent on the master host. The options are 
-r, -h, -i, -v, -w, -y, and -b and have the same semantics as options on the command line except they only apply to the files 
in the source list. The login name used on the destination host isthe same as the local host unless the destination nameisof 
the format iogin@host. 

The notify command is used to mail the list of files updated (and any errors that may have occurred) to the listed names. If 
no @ appears in the name the destination host is appended to the name (for example namei@host, name 2 @host). 

The except command is used to update all of the files in the source list except for the files listed in namelist. This is usually 
used to copy everything in a directory except certain files. 

The except_pat command is like the except command except that pattern list isa list of regular expressions (see ed(l) for 
details). If one of the patterns matches some string within afilename that file will be ignored. Note that because \ isaquote 
character, it must be doubled to become part of the regular expression. Variables are expanded in pattern list, but not shell 
file pattern-matching characters. To include a $, it must be escaped with \. 

The special command is used to specify sh(l) commands that are to be executed on the remote host after thefile in name 
list is updated or installed. If the name list is omitted, then the shell commands will be executed for every file updated or 
installed. The shell variable file issdt to the current filename before executing the commandsin string. string starts and 
ends with double quotes (■) and can cross multiple lines in distme. M ultiple commands to the shell should be separated by 
a semicolon. Commands are executed in the user's home directory on the host being updated. The special command can be 
used to rebuild private databases, and so on after a program has been updated. 

Thefollowing isa small example: 

HOSTS = ( matisse rootOarpa ) 

FILES = ( /bin /lib /usr/bin /usr/games 
/usr/include/{*.h,{stand,sys,vax*,pascal,machine}/*.h 
/usr/lib /usr/man/man? /usr/ucb /usr/local/rdist ) 

EXLIB = ( Mail.rc aliases aliases.dir aliases.pag crontab dshrc sendmail.cf 
sendmail.fc sendmail.hf sendmail.st uucp vfont ) 

${FILES} -> ${H0STS} install -R ; except /usr/lib/${EXLIB} ; except /usr/games/lib ; 
special /usr/lib/sendmail "/usr/lib/sendmail -bz" ; 

srcs: /usr/src/bin -> arpa except pat ( \\.o\$ /SCCS\$); 

IMAGEN = (ips dviimp catdvi) 

imagen: /usr/local/${IMAGEN} -> arpa install /usr/local/lib ; notify ralph ; 

${FILES} :: stamp.cory notify root@cory ; 

FILES 

distfiie Input command file 

/tmp/rdist* Temporary filefor update lists 

SEE ALSO 

sh( 1), csh(l), stat(2) 

HISTORY 

Therdist command appeared in BSD 4.3. 
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DIAGNOSTICS 

A complaint about mismatch of rdist version numbers may really stem from some problem with starting your shell; for 
example, you are in too many groups. 

BUGS 

Source files must reside on the local host where rdist is executed. 

There is no easy way to have a special command executed after all files in a directory have been updated. 

Variable expansion only worksfor name lists; there should beageneral macro facility, 
rdist abortson files that have a negative mtimefbeforej an 1,1970). 

There should be a force option to allow replacement of nonempty directories by regular files or symlinks. A means of 
updating file modes and owners of otherwise identical files is also needed. 

BSD 4.3, 30 December 1993 


reconfig 

reconfig— Con vert old Xconfigto new XF86Config 

SYNOPSIS 

reconfig < Xconfig > XF86Config 

DESCRIPTION 

The reconfig program converts the Xconfig file format used in XFree86 versions prior to 3.1 into the XF86Config format 
currently used. TheXF86Config format contains more information than the Xconfig format, so manual editing is required 
after converting. 

SEE ALSO 

XFree86(l), XF86Config(4/5), xf86config(l) 

AUTHOR 

Gertjan Akkerman 

BUGS 

Comment lines are stripped out when converting. 


XFreeB6 Verson 3.1.1 
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ref 

ref- D isplay a C function header 

SYNOPSIS 

ref J-tl [-x] [-c class]... |-f file]... tag 

DESCRIPTION 

ref quickly locates and displays the header of a function. To do this, ref looksin the tags file for the line that describes the 
function, and then scans the source file for the function. When it locates thefunction, it displays an introductory comment 
(if there is one), the function's declaration, and the declarations of all arguments. 

SEARCH METHOD 

ref uses a fairly sophisticated tag look-up algorithm. If you supply afilename via -f file, then eivis first scansthe tags 
file for a static tag from that file. This search is limited to the tags file in the current directory. 

If you supply a class name via -c class, then eivis searches for a tag from that class. This search is not limited to the 
current directory; You can supply a list of directories in the environment variable tagpath, and ref will search through the 
tags file in each directory until it finds a tag in the desired class 

If that fails ref will then try to look up an ordinary global tag. Thissearch checks all of the directories listed in tagpath, too. 
If the tag being sought doesn't contain any colons, and you haven't given a -x flag, then any static tags in a tags file will be 
treated as global tags. 

If you've given the -t flag, then ref will simply output the tag line that it found, and then exit. Without -t, though, ref 
will search for the tag line It will try to open the source file, which should bein thesame directory as the tags file where the 
tagwasdiscovered. If the source file doesn't exist, or is unreadable, then ref will try to open a file called refs in that 
directory. Either way, ref will try to locate the tag, and display whatever it finds 

INTERACTION WITH eivis 

ref isused by theeivis shift-x command. If the cursor islocated on aword such as splat, in thefilefoo.c, then eivis will 
invoke ref with the command ref -f foo.c splat. 

If eivis has been compiled with the -dexternal_tags flag, then eivis will use ref to scan the tags files This is slower than 
the built-in tag searching, but it allows eivis to access the more sophisticated tag lookup provided by ref. Other than that, 
external tags should act exactly like internal tags. 

OPTIONS 

-t 0 utput tag info, instead of thefunction header. 

-t file The tag might be a static function infiie. You can use several -fflagsto have ref consider static tags 

from more than one file 

-c class The tag might be a member of class class. You can use several -cflagsto have ref consider tags from 
more than one class 

FILES 

tags List of function names and their locations generated by ctags 
refs Function headers extracted from source files (optional) 

ENVIRONMENT 

tagpath Listof directoriesto be searched. The elements in the list are separated by either semicolonsffor M S-DOS, 

Atari TO S, and AmigaD os), or by colons (every other operating system). For each operating system, ref 
has a built-in default which is probably adequate. 
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NOTES 

You might want to generate a tags f i I e for th e di recto ry that contains the source code for standard C library on your system. 
If licensing restrictions prevent you from making the library source readable by everybody, then you can havectags generate 
a refs file, and make refs readable by everybody. 

If your system doesn't come with the I i brary source code then perhaps you can produce somethi ng workable from the lint 
libraries 

SEE ALSO 

elvis(l), ctags(l) 

AUTHOR 

Steve Kirkendall (kirkenda@cs.pdx.edu) 

reset 

reset— Reset the terminal 

SYNOPSIS 

DESCRIPTION 

reset calls tput(l) with the clear, rmacs, rmm, rmui, rsi, rs 2 , and rs3 arguments. This causes tput to send appropriate 
reset strings to the terminal based on information in /etc/termcap (fortheG N U or BSD tput) or in the terminfo database 
(forthencurses tput). This sequence seems to be sufficient to reset the Linux VC's when they start printing "funny¬ 
looking" characters. For good measure, stty(l) iscalled with the sane argument in an attempt to gdt Cooked mode back. 

SEE ALSO 

reset(l), stty(l), tput(l) 

AUTHOR 

Rik Faith (faith@cs.unc.edu) 

Linux0.99,10 October 1993 


resize 

resize— Set termcap and terminal settings to current xterm window size 

SYNOPSIS 

resize [ -u | -c ][-s [ row col ]] 

DESCRIPTION 

resize prints a shell command for setting the term and termcap environment variables to indicate the current size of xterm 
window from which the command is run. For this output to take effect, resize must either be evaluated as part of the 
command line (usually done with a shell alias or function) or else redirected to afile that can then be read in. FromtheC 
shell (usually known as /bin/csh), thefollowing alias could be defined in the user's.cshrc: 

% alias rs 'set noglob; eval 'resize 11 
After resizing the window, the user would type: 





rgb3toppm 




Users of versions of the Bourne shell (usually known as/bin/sh) that don't have command functions will need to send the 
output to a temporary file and the read it back in with the. command: 

$ resize > /tmp/out 
$ . /tmp/out 

OPTIONS 

Thefollowing options may be used with resize: 

-u This option indicates that Bourne shell commands should be generated even if the user's current 

Shell isn't /bin/sh. 

-c This option indicates that C shell commands should be generated even if the user's current shell 

isn't /bin/csh. 

-s [rows columns] This option indicates that Sun console escape sequences will be used instead of the special xterm 
escape code If rows and coi umns are given, resize will ask the xterm to resize itself. However, the 
window manager may choose to disallow the change 

FILES 

/etc/termcap Forthebase termcap entryto modify 
■/ .cshrc User'saliasforthecommand 

SEE ALSO 

csh(l), tset(l), xterm(l) 

AUTHORS 

M ark Vandevoorde(M IT-Athena), Edward M oy(Berkeley) 

Copyright© 1984,1985 by XConsortium 
See X(l) for a complete copyright notice. 

BUGS 

The -uor -c must appear to the left of -s if both are specified. 

X Version 11 Release 6 


rev 

rev- Reverse lines of a file 

SYNOPSIS 

rev [file] 

DESCRIPTION 

The rev utility copies the specified files to the standard output, reversing the order of characters in every line. If no files are 
specified, the standard input is read. 

21 March 1992 


rgb3toppm 

rgb3toppm— C ombine three portable graymaps into one portable pixmap 
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SYNOPSIS 

rgb3toppmr edpgmf i I e greenpgmfi I e bluepgmfile 

DESCRIPTION 

rgb3toppm reads three portable graymapsas input and combines them and produces one portable pixmap as output. 

SEE ALSO 

ppmtorgb3(l), pgmtoppin(l), ppmtopgm(l), ppm(5), pgm(5) 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

15 February 1990 

rlog 

riog— Print log messages and other information about RC S files 

SYNOPSIS 

rlog [options [file ... 

DESCRIPTION 

nog prints information about RCS files 

Pathnamesmatchingan rcs suffix denote RCS files; all others denote working files. Names are paired as explained in ci(l). 
nog prints thefollowing information for each RCS file: RCS pathname working pathname head (the number of the latest 
revision on thetrunk), default branch, access list, locks symbolic names suffix, total number of revisions number of 
revisions selected for printing, and descriptive text. Thisisfollowed by entries for the selected revisionsin reverse chronologi¬ 
cal order for each branch. For each revision, riog prints revision number, author, date/time state, number of lines added/ 
deleted (with respect to the previous revision), locker of the revision (if any), and log message. All times are displayed in 
Coordinated Universal Time(UTC) by default; thiscan be overridden with -z. Without options nog prints complete 
information. T he options below restrict this output. 

-l IgnoreRCSfilesthathavenolockssdt.Thisisconvenientincombination with -h, -i,and -r. 

-r PrintonlythenameoftheRCsfile. Thisisconvenientfortranslatingaworkingpathnameinto an RCS 

pathname. 

-h Print only the RCS pathname, working pathname, head, default branch, access list, locks symbolic names, 

and suffix. 

-t Printthesameas -h, plus the descri pti ve text. 

-N Do not print the symbolic names. 

-b Print information about the revisions on the default branch, normally the highest branch on thetrunk. 

- dd a t e s Print information about revisions with a checkin date/time in the ranges given by the semicolon-separated 

list of d a t e s . A range of the form di <d2 or d2>di selects the revisions that were deposited between di and 
d2 exclusive. A range of the form <d or d> selects all revi si on s earl i er th an d. A range of the form d< or >d 
selects all revisions dated later than d. If < or > isfollowed by =, then the ranges are inclusive, not exclusive 
A range of the form d selects the single latest revision dated d or earlier. The date/time strings d, di, and 
d2arein the free format explained in co(l). Quoting is normally necessary, especially for < and >. Note 
that the separator is a semicolon. 

-i[i ockers ] Print information about locked revisions only. In addition, if the comma-separated list i ockers of login 
namesisgiven, ignoreall locksotherthanthoseheld bythei ockers. Forexample, nog -l -r -iwft 
rcs/* prints the name of RCS files locked by the user wft. 
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-r[r evi si ons ] Print information about revisions given in the comma-separated list re»i si ons of revisions and ranges. A 
range revi: rev2 means revisions revi to rev2 on thesame branch, :rev means revisionsfrom the 
beginning ofthe branch up to and including rev, and rev: meansrevisionsstartingwith rev to the end of 
the branch containing rev. An argument that is a branch meansall revisionson that branch. A range of 
branches means all revisionson the branches in that range A branch followed by a . means the latest 
revision in that branch. A bare -r with no revisions means the latest revision on the default branch, 
normally the trunk. 

-sst at es Print information about revisions whose state attributes match one of the states given in the comma- 

separated list states. 

- w [ i ogi ns ] Print information about revisions checked in by users with login namesappearing in the comma-separated 
list logins. If logins is omitted, the user's login isassumed. 

-t Thisoption has no effect; it is present for compatibility with other res commands 

-v Print the RCS version number. 

-vn Emulate RCS version n when generating logs (See co(l) for more details) 

-xsuffi xes Uses uf f i xe s to characterize RCS files. (See ci(l) for details) 


nog prints the intersection of the revisions selected with the options -d, -1, -s, and -w, intersected with the union ofthe 
revisions selected by -b and -r. 

-zzone Specifies the date output format, and specifies the default time zonefor date in the -ddates option. The 

zone should be empty, a numeric UTC offset, or the special string lt for local time. The default isan 
empty zone, which usesthetraditional RCS format of UTC without any timezone indication and with 
slashes separating the parts of the date; otherwise times are output in iso 8601 format with timezone 
indication. For example if local time is January 11,1990,8 p.m. Pacific Standard Time, eight hours west 
of UTC, then thetime is output as follows: 

option time output 


-z 1990/01/12 04:00:00 (default) 

-zLT 1990-01-11 20:00:00-08 

-z+05:30 1990-01-12 09:30:00+05:30 


EXAMPLES 

H ere are four riog commands: 
rlog -L -R RCS/* 
rlog -L -h RCS/* 
rlog -L -1 RCS/* 
rlog RCS/* 

Thefirst command prints the names of all RCS files in the subdirectory rcs that have locks The second command prints 
the headers of those files, and the third prints the headers plus the log messages of the locked revisions The last command 
prints complete information. 

ENVIRONMENT 

rcsinit 0 ptions prepended to the argument list, separated by spaces. (See ci(l) for details) 


DIAGNOSTICS 

The exit status is zero if and only if all operations were successful. 
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IDENTIFICATION 

Author: Walter F.Tichy 

M anual Page Revision: 5.9; Release D ate: 1995/06/16 
Copyright© 1982,1988,1989 Walter F. Tichy 
Copyright© 1990,1991,1992,1993,1994,1995 Paul Eggert 

SEE ALSO 

ci(l), co(l), ident(l), rcs(l), rcsdiff(l), rcsintro(l), rcsmerge(l), rcsfile(5) 

"RCS-A System for Version Control" by Walter F. tichy, Software-Practice & Experience 15, 7 (July 1985), pages 637-654. 

BUGS 

The separator for revision ranges in the -r option used to be ■ instead of:, but this leads to confusion when symbolic names 
contain -. For backwards compatibility, riog -r still supports the old - separator, but it warns about thisobsolete use. 

GNU, 16 ]unel995 


rlogin 

riogin-Remote login 

SYNOPSIS 

rlogin [ -8EKLdx] [-e char] [-k realm] [-1 username] host 

DESCRIPTION 

riogin starts a terminal session on a remote host host. 

riogin first attempts to use the Kerberos authorization mechanism, described in thefollowing subsection. If the remote host 
does not support Kerberos, the standard Berkeley authorization mechanism isused. The options are as follows 
-8 The -8 option allows an eight-bit input data path at all times; otherwise, parity bits are stripped except when the 
remote side's stop and start characters are other than - s / * a. 

-e The -e option stopsany character from being recognized as an escape character. W hen used with the -8 option, 
this provides a completely transparent connection. 

-k The -Koption turnsoff all Kerberosauthentication. 

-l The -l option allows the riogin session to be run in utout mode.(Seetty(4) for details). 

-d The -d option turns on socket debugging (see the setsockopt(2) man page) on the top sockets used for 

communication with the remote host. 

-e The -e option allows user specification of the escape character, which isthetilde(') by default. Thisspecification 
may be as a literal character, or as an octal value in theform nnnn. 

-k The -koption requests riogin to obtain tickets for the remote host in realm realm instead of the remote host's 
realm as determined by krb_reaimofhost(3). 

-x The -x option turns on D ES encryption for all data passed via the riogin session. This may impact response time 
and CPU utilization, but provides increased security. 

A line of theform <escape char> disconnects from the remote host. Similarly, the line <escape char>~zwill suspend the 
rlogin session, and <escape charxdelayed - suspend char> suspends the Send portion Of the rlogin, but allows Output 
from the remote system. By default, the tilde (') character istheescape character, and normally control -y('y) is the 
delayed-suspend character. 

All echoing takes place at the remote site, so that (except for delays) the riogin is transparent. Flow control via "s/ “q and 
flushing of input and output on interrupts is handled properly. 




rm 

KERBEROS AUTHENTICATION 

Each user may have a private authorization list in thefile in hisor her home directory. Each line in thisfile should contain a 
Kerberosprincipal nameoftheform principal, instance (@reaim). Iftheoriginating user ^authenticated to oneof the 
principals named, access is granted to the account. Theprincipai accountname. (@iocaireaim) isgranted access if there is 
no file. Otherwise, a login and password will be prompted for on the remote machine as in iogin(l). To avoid certain 
security problems, thefile must beowned by the remote user. 

If Kerberos authentication fails, a warning message is printed and the standard Berkeley noginisused instead. 

ENVIRONMENT 

Thefollowing environment variable is utilized by riogin: 
term Determinestheuser'sterminaltype 

SEE ALSO 

rsh(l), kerberos(3), krb_sendauth(3), krb_realmof host(3) 

HISTORY 

The riogin command appeared in BSD 4.2. 

BUGS 

riogin will be replaced by teinet(l) in the near future 
M oreof theenvironment should be propagated. 

BSD 4.2, 27July 1991 



rm 

rm— Removefiles 

SYNOPSIS 

rm [-dfirvR] [--directory] [--force] [--interactive] [--recursive] 

[--help] [--version] [--verbose] name... 

DESCRIPTION 

This manual page documents the gnu version of rm. rm removes each specified file. By default, it does not remove directories 
If a file is unwritable the standard input is a tty, and the -for - -force option is not given, rm promptsthe user for whether 
to remove the file. If the response does not begin with yory, thefile is skipped. 

GNU rm, like every program that uses the getopt function to parse its arguments, lets you use the - - option to indicate that 
all following arguments are nonoptions. To remove a file called -f in the current directory, you could type either 


or 


TheU NIX ™ program's use of a single - for this purpose predates the development of the getopt standard syntax. 

OPTIONS 

-d, - -directory Remove directories with unlink instead of rmdir, and don't require a directory to be empty before 

trying to unlink it. Only works for the superuser. Because unlinking a directory causes any files in 
thedeleted directory to become unreferenced, it is wise to fsckthefilesystem after doing this 
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Ignore nonexistent files and never prompt the user. 

Prompt whether to removeeach file. If the response does not begin with y or y, the file is skipped. 
Remove the contents of directories recursively. 

Print the name of each file before removing it. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output, then exit successfully. 

GNU FileUtilities 

rmdir 

rmdir—Remove empty directories 

SYNOPSIS 

rmdir [-p] [--parents] [--help] [--version] dir... 

DESCRIPTION 

This manual page documents the GN U version of rmdir. rmdir removes each given empty directory. If any nonoption 
argument does not refer to an existing empty directory, it is an error. 

Remove any parent directories that are explicitly mentioned in an argument, if they become empty 
after the argument file is removed. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output, then exit successfully. 

GNU FileUtilities 

rmmod— U nload loadable modules 

SYNOPSIS 

rmmod [ -r ] module ... 

DESCRIPTION 

rmmod unloads loadable modules from the kernel. 

rmmod tries to unload a set of modules from the kernel, with the restriction that they are not in use and that they are not 
referred to by other modules. 

If more than one module is named on the command line, the modules will be removed in the given order. This supports 
unloading of stacked modules. 

With the option - r, a recursive removal of modules will be attempted. This means that if atop module in a stack is named 
on thecommand line, all modules that are used by this module will be removed as well, if possible. 

SEE ALSO 

insmod(l), lsmod(l), ksyms(l), modules(2) 


OPTIONS 

-p, - - parents 


rmmod 


-i, - -interactive 
-r, -R, - -recursive 
-v, - -verbose 

- -help 

- -version 
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HISTORY 

The module support was first conceived byAnonymous(asfarasl know...). Linux version by BasLaarhoven 
(bas@vimec.nl), 0.99.14 version by Jon T ombs( jon@gtex02.us.es), extended by Bjorn Ekwall (bj0m@biox.se). 

BUGS 

rmmod might have some but they are well hidden. 

Linux, 14 May 1995 


rnews 

mews— Receive news from a U U C P connection 

SYNOPSIS 

DESCRIPTION 

mews reads messages sent by a downstream uucp newsfeed and sends them to the local InterN etN ews server. The message is 
read from the specified input file or standard input if no input is named. 

If the -sflag is used, then mews will connect to the specified host. If theflag is not used, it will try to connect to the server 
by openingaUN IX-domain stream connection. If that fails, it will try to open a TCP connection to the default remote 
server. 

If the server is not available the message is spooled into a new file created in the /var/spooi/rnews directory. The -u flag 
may be used to send all spooled messages to the server when it becomes available again, andean be invoked regularly by 
cron(8). 

W hen sent over uucp, U senet articles are typically joined in a single batch to reduce the uucp overhead. Batches can also be 
compressed, to reduce the communication time. If a message does not start with a number sign (#) and an exclamation 
point, then the entire input is taken as a single news article. If it does start with those two characters, then the first line is read 
and interpreted as a batch command. 

If the command is#i mews nnn.wherennn isa number, then thenextnnn bytes (starting with the next line) are read as a 
news article. 

If the command is#i cunbatch, then the rest of input is fed to thecompress(l) program with the -d flag to uncompress it, 
and the output of this pipe is read as input from mews. This is for historical compatibility—there isno program named 
cunbatch. A compressed batch will start with a#i cunbatch line, then contain a series of articles separated by #1 mews nnn 
lines. 

If the command isany other word, then mews will try to execute a program with that name in the directory /news/bin/ 
mews. The batch will be fed into the program's standard input, and the standard output will be read back as input into 

If mews detects any problems with an article, such asa missing header or an unintelligible reply from the server, it will save a 
copy of theartide in the/var/spooi/rnews/bad directory. If the - v flag is used, it will print a notice of all such errorson the 
standard error, naming the input file (if known) and printing the first few characters of the input. Errors are always logged 
through sysiog(3). 

If the - h flag isgiven, or failing that, the environment variable uujiachine isset, then mews will log the M essage-ID and 
host for each article offered to the server via sysiog(3). Logging will only be done if the value is not an empty string. 

BUGS 

mews cannot process articles that have embedded \os in them. 
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HISTORY 

W ritten by Rich $alz (rsaiz@uunet. uu. net) for InterN dtN ews. 

SEE ALSO 

innd(8). 

rpcgen 

rpcgen—An RPC protocol compiler 

SYNOPSIS 

rpcgen infile 

rpcgen [-D name[= value]] [-T] [-K secs] infile 
rpcgen -c -h]-1]-m]-t [-0 outfile] infile 
rpcgen [-1] -s nettype ]-o outfile] infile 
rpcgen -n netid [-0 outfile] infile 

DESCRIPTION 

rpcgen isa tool that generate C codeto implement an RPC protocol. Theinput to rpcgen isa language similar to C known 
asRPC language(RemoteProcedureCall Language), rpcgen is normally used asin the first synopsis where it takes an input 
fileand generates up to four output files Iftheinfiieisnamed proto.x, then rpcgen will generate a header file in proto.h, 
xdr routines in proto_xdr.c, server-side stubs in proto_svc.c, and client-side stubs in proto_cint.c. 

With the -t option, it will also generate the RPC dispatch table in proto_tbi.i. With the -sc option, it will also generate 
sample code that would illustrate how to use the remote procedures on the client side This code would be created in 
proto_ciient.c. With the -Ss option, it will also generate a sample server code that would illustrate how to write the 
remote procedures This code would be created in proto_server.c. The server created can bestarted both by the port 
monitors (for example inetd or listen) or by itself. When it isstarted by a port monitor, it creates servers only for the 
transport for which the file descriptor 0 was passed. The name of the transport must be specified by setting up the environ¬ 
mental variable pm_transport. 

When the server generated by rpcgen is executed, it creates server handles for all the transports specified in netpath 
environment variable, or if it is unset, it creates server handles for all the visible transports from /etc/netconfigfile Note: 
thetransports are chosen at runtimeand not at compile time. When the server is self-started, it backgrounds itself by default. 
A special define symbol rpc_svc_fg can be used to run the server process in the foreground. The second synopsis provides 
special features that allow for the creation of more sophisticated RPC servers. These features include support for user- 
provided #def ines and RPC dispatch tables Theentriesin theRPC dispatch table contain 

■ Pointers to the service routine corresponding to that procedure 

■ A pointer to the input and output arguments 

■ The size of these routines 

A server can use the dispatch table to check authorization and then to execute the service routine; a client library may use it 
to deal with the details of storage management and xdr data conversion. The other three synopses shown in the preceding 
paragraph are used when one does not want to generate all the output files but only a particular one. (Some examples of 
their usage is described in the"Exampl£' subsection.) When rpcgen isexecuted with the -s option, it creates servers for that 
particular class of transports. W hen executed with the -n option, it creates a server for the transport specified by netid. If 
infiie is not specified, rpcgen accepts the standard input. TheC preprocessor.ee -e (see cc(l) for details), isrun on the 
input file before it is actually interpreted by rpcgen. For each type of output file, rpcgen defines a special preprocessor 
symbol for use by the rpcgen programmer, as follows 
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rpc_hdr Defined when compiling into header files 

rpc_xdr Defined when compiling into XDR routines 

rpc_svc Defined when compiling into server-side stubs 

rpc_clnt Defined when compiling into client-side stubs 

rpc_tbl Defined when compiling into rpc dispatch tables Any line beginning with % is passed directly into the 

output file, uninterpreted by rpcgen. For every data type referred to in inf lie, rpcgen assumes that there 
exists a routine with the string xdr prepended to the name of the data type If this routine does not exist in 
theRPC/XDR library, it must be provided. Providing an undefined data type allows customization of 
XD R routines. The following optionsare available 

-a Generate all the files including sample code for client and server side 

-b ThisgeneratescodefortheSunOS4.1 style of rpc. It isfor backwardscompatibility. 

This is the default. 

-5 This generates code for the Sy^/r4 style of rpc. Itisused by the Transport 

Independent RPC thatisin Svr4 systems. By default, rpcgen generates code for 
SunO S4.1 type of rpc. 

-c Compile into XDR routines. 

-c Generate code in ANSI C. This option also generates code that could be compiled 

with theC-H-compiler. This is the default. 

-k Generate code in K& R C. Thedefault isAN SI C. 

- Dn a me [ =v a i ue] Defineasymbol name. Equivalent to the #define directive in the source. If no va i ue 
isgiven, value is defined as i. This option may be specified more than once. 

-h Compile into C data-definitions (a header file), -t option can be used in conjunc¬ 

tion to producea header file that supports RPC dispatch tables. 

-i Generate a service that can be started from inetd. Thedefault is to generate a static 

service that handles transports selected with -s. Using -i allows starting a service by 
either method. 

-k secs By default, services created using rpcgen wait 120 seconds after servicing a request 

before exiting. T hat interval can be changed using the - k flag. To create a server that 
exits immediately upon servicing a request, -k 0 can be used. To create a server that 
never exits, the appropriate argument is - k - 1. 

When monitoring for a server, some port monitors, such asiistenjlM), always 
spawn anew process in response to a service request. If it is known that a server will 
be used with such a monitor, the server should exit immediately on completion. For 
such servers, rpcgen should be used with -k - 1. 

-1 Compile into client-side stubs. 

-m Compile into server-side stubs, but do not generate a main routine This option is 

useful for doing callback-routines and for users who need to write their own main 
routine to do initialization. 

-n neti d Compileinto server-side stubs for the transport specified byneti d. There should be 

an entry for net i d in thenetconfig database. This option may be specified more 
than once so as to compile a server that serves multiple transports. 

-n U se the newstyle of rpcgen. This allows procedures to have multiple arguments It 

also uses the style of parameter passing that closely resembles C. So, when passing an 
argument to a remote procedure, you do not have to pass a pointer to the argument 
but the argument itself. This behavior is different from the old style of rpcgen- 
generated code The new style is not the default case because of backwards 
compatibility. 

-0 out f i 1 e Specify the name of the output file If none is specified, standard output is used (c, 

-h, -1, -m, -n, -s, -sc, -ss, and -t modesonly). 
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Compile into server-side stubs for all the transports belonging to the class nettype. 
The supported classes are netpath, visible, circuit_n, circuit_v, datagram_n, 
datagram^, tcp, and udp. See rpc(3N) for the meanings associated with these 
classes. This option may be specified more than once. N ote: The transports are 
chosen at runtime and not at compile time. 

Generate sample code to show the use of remote procedure and howto bind to the 
server before calling the client-side stubs generated by rpcgen. 

G enerate skeleton code for the remote procedures on the server side. You would 
need to fill in the actual code for the remote procedures 
Compileinto RPC dispatch table. 

Generate the code to support RPC dispatch tables. Theoptions -c, -h, -1, -m, u, 
and -t are used exclusively to generate a particular type of file while the options -d 
and -t are global and can be used with the other options 


NOTES 

The RPC language does not support nesting of structures. As a workaround, structures can be declared at the top level, and 
their name used inside other structures in order to achieve the same effect. N ame clashes can occur when using program 
definitions because the apparent scoping does not really apply. M ost of these can be avoided by giving unique names for 
programs versions procedures and types The server codegenerated with the -n option refers to the transport indicated by 
netid and hence is very site-specific. 


EXAMPLE 

Thefollowing example: 

$ rpcgen -T prot.x 

generates five files prot.h, prot_clnt.c, prot_svc.c, prot_xdr.c, and prot_tbl.i. 

This example: 

$ rpcgen -h prot.x 

sends theC data-definitions (header file) to the standard output. 

To send the test version of the -dtest, server-side stubs for all the transport belonging to the class datagrams to standard 
output, use 

$ rpcgen -s datagram_n -DTEST prot.x 

To create the server-side stubs for the transport indicated byneti <j tcp, use 

$ rpcgen -n tcp -o prot_svc.c prot.x 

SEE ALSO 

cc(l). 

rsh 

rsh—Remote shell 

SYNOPSIS 

rsh [-Kdnx] [-k realm] [-1 username] host command 

DESCRIPTION 


I executes command on 
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rsh copies its standard input to the remote command, the standard output of the remote command to its standard output, 
and the standard error of the remote command to its standard error. Interrupt, quit, and terminate signals are propagated to 
the remote command; rsh normally terminates when the remote command does. The options are as follows: 

-k T urnsoff all Kerberos authentication. 

-d Using setsockopt(2), turns on socket debugging on the TCP sockets used for communication with the remote 
host. 

-k Causes rsh to obtain tickets for the remote host in realm instead of the remote host's realm as determined by 
krb_realmof host(3). 

-i By default, the remote username is the same asthe local username. The -1 option allows the remote name to be 
specified. Kerberos authentication isused, and authorization isddtermined asin riogin(l). 

-n The -n option redirects input from the special device (See the "Bugs" section of this manual page.) 

-x The -x option turns on D ES encryption for all data exchange This may introduce a significant delay in response 

time. 

If no command is specified, you will be logged in on the remote host using riogin(l). 

Shell metacharacters that are not quoted are interpreted on local machine, while quoted metacharacters are interpreted on 
the remote machine For example, the command; 

rsh otherhost cat remotefile » localfile 

appends the remote file remotefiie to the local file locaifiie, while 

rsh otherhost cat remotefile » other remotefile 

appends remotefile to other remotefile. 

FILES 

/etc/hosts 

SEE ALSO 

rlogin(l), kerberos(3), krb sendauth(3), krb_realmofhost(3) 

HISTORY 

The rsh command appeared in BSD 4.2. 

BUGS 

If you are using csh(l) and put a rsh in the background without redirecting its input away from the terminal, it will block 
even if no reads are posted by the remote command. If no input isdesired you should redirect theinput of rsh to using the 
-n option. 

You cannot run an interactive command (rogue(6) or vi(l), for example) using rsh; use riogin(l) instead. 

Stop signals stop the local rsh process only; this is arguably wrong, but currently hard to fix for reasons too complicated to 
explain here. 

BSD 4.2, 24 July 1991 


rstart 

rstart—A sample implementation of a Remote Start client 

SYNOPSIS 

rstart [ - c context] [ - g ] [-1 username] [-v] hostname command a r g s ... 
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DESCRIPTION 

rstartisa simple implementation of a Remote Start client as defined in "A Flexible Remote Execution Protocol Based on 
rsh." It uses rsh as its underlying remote execution mechanism. 

OPTIONS 

-c context Thisoption specifiesthe context in which thecommand isto berun. A context specifies a general 

environment the program isto berun in. The details of this environment are host-specific; the intent is 
that the client need not know how the environment must be configured. If omitted, the context defaults to 
x. This should be suitablefor running x programs from the host's "usual" x installation. 

-g Interprets command as a generic command, as discussed in the protocol document. This is intended to allow 

common applicationsto be invoked without knowing what they are called on the remote system. 
Currently, the only generic commands defined areierminai, LoadMomtor, Listcontexts.and 
ListGenericCommands. 

-i user name Thisoption is passed to the underlying rsh; it requests that the command berun as the specified user. 

-v Thisoption requests that rstart beverbosein its operation. Without this option, rstart discards output 

from the remote's rstart helper, and directs the rstart helper to detach the program from the rsh 
connection used to start it. W ith thisoption, responses from the helper are displayed and the resulting 
program is not detached from the connection. 

NOTES 

This is a trivial implementation. Far more sophisticated implementations are possible and should be developed. 
Error-handling is nonexistent. Without -v, error reports from the remote are discarded silently. With -v, error reports are 
displayed. 

T he $display environment variable is passed. If it starts with a colon, the local hostname is prepended. The local domain 
nameshould be appended to unqualified hostnames, but isn't. 

The $session_manager environment variable should be passed, but isn't, 
xi i authority information is passed for the current display. 

ice authority information should be passed, but isn't. It isn't completely clear how rstart should select what ICE authority 
information to pass. 

Even without -v.thesample rstart helper will leaveashell waiting for the program to complete. This causes no real harm 
and consumes relatively few resources, but if it is undesirable it can be avoided by explicitly specifying the exec command to 
the shell, for example, 0 rstart somehost exec xterm. 

This is obviously dependent on thecommand interpreter being used on the remote system; the example given will work for 
the Bourne and C shells 

SEE ALSO 

rstartd(l), rsh(l), "A Flexible Remote Execution Protocol Based on rsh" 

AUTHOR 

Jordan Brown, QuarterdeckOfficeSystems 

X Version 11 Release6 

rstartd 

rstartd—A sample implementation of a Remote Start rsh helper 
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SYNOPSIS 

rstartd 

rstartd.real [-c configfilename] 

DESCRIPTION 

rstartd isan implementation of a Remote Start "helper" as defined in "A Flexible Remote Execution Protocol Based 
On rsh." 

This document describes the peculiarities of rstartd and how it is configured. 

OPTIONS 

-c conf i gf i i ename Thisoption specifiesthe global configuration filethat rstartd isto read. Normally, rstartd isa 
shell script that invokes rstartd. real with the -c avitch, allowing local configuration of the 
location of the configuration file. If rstartd.real is started without the -c option, it reads 
<xRoot>/nb/xi i / rstart/cont ig, where <xRoot> refers to the root of the X11 install tree. 

INSTALLATION 

It iscritical to successful interoperation of the Remote Start protocol that rstartd be installed in a directory that is in the 
default search path, so that default rsh requests and the nk will beabletofind it. 

CON FIGURATION AND OPERATION 

rstartd is by design highly configurable. One would like things like configuration file locations to be fixed, so that users and 
administrators can find them without searching, but reality is that no two vendors will agreeon where things should go, and 
nobody thinksthe original location is "right." Thus, rstartd allows the relocation of all of its files and directories 
rstartd hasa hierarchy of configuration files that are executed in order when a request is made. They are global config, per¬ 
user ("local") config, global per-context config, per-user ("local") per-context config, config from request. 

As you might guessfrom the presence of config from request, all of the config files are in the format of an rstart request, 
rstartd defines a few additional keywords with the internal - prefix for specifying its configuration, 
rstartd starts by reading and executing the global config file. Thisfilewill normally specify the locations of the other 
configuration files and any system-wide defaults. 

rstartd will then read the user's local config file default name$HOME/ . rstart. 
rstartd will then start interpreting the request. 

Presumably, one of thefirst linesin the request will beacoNTEXT line. The context nameisconverted to lowercase, 
rstartd will read the global config file for that context, default name <xRoot>/iib/xn/rstart/contexts/<name>, if any. 

It will then read the user's config file for that context, default name $home/. rstart. contexts /<name>, if any. 

(If neither of these exists, rstartd aborts with a Failure message) 

rstartd will finish interpreting the request, and execute the program specified. This allows the system administrator and the 
user a large degree of control over the operation of rstartd. The administrator has final say, because the global config file 
doesn't need to specify a per-user config file If it does, however, the user can override anything from the global file, and can 
even completely replace the global context config files. 

The config files have a somewhat more flexible format than requests do; they are allowed to contain blank lines and lines 
beginning with # are comments and ignored. (#s in the middle of I ines are data, not comment markers.) 
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Any commands run are provided a few useful pieces of information in environment variables. The exact names are 
configurable, but the supplied defaults are 

$rstart_context The name of the context 

$rstart_global_contexts T he global contexts directory 

$rstart_local_contexts The local contexts directory 

$rstart_global_commands T he global generic commands directory 

$rstart_local_commands The local generic commands directory 

$rstart_{global, local}_contexts should contain one special file @List, which contains a list of the contexts in that 
directory in theformat specified for Listcontexts. The supplied version of Listcontexts will cat both the global and local 
copies of @List. 

Generic commands are searched for in several places: (defaults) 

Per-user per-context directory $home/. rstart. commands/<context> 

Global per-context directory <XRoot>/lib/X11/rstart/commands/<context> 

Per-user all-contexts directory $home/. rstart. commands 

Global all-contexts directory (<XRoot>/lib/X11/rstart/commands) 

(Yes, thismeansyou can't have an all-contexts generic command with the same name as a context. It didn't seem like a big 
deal.) 

E ach of these directories should have a file called @List that gives the names and descriptions of the commands in that 
directory in theformat specified for ListGenertcCommands. 

CONFIGURATION KEYWORDS 

There are several special rstart keywords defined for rstartd configuration. Unless otherwise specified, there are no 
defaults: related features are disabled in this case. 

Internal-Registries name ...—G ivesa space-separated listof misc registriesthatthissystem understands. (Registries 
other than these are accepted but generate a warning.) 

Internal-Local-Default relative_f ilename- Gives the name ($HOME relative) Of the per-USer COnfig file. 
internal-global-contexts absoiute_directory_name— G ives the name of the system-wide contexts directory. 
internal-local-contexts reiative_directory_name— G ivesthe name ($home relative) of the per-user contexts directory. 
internal-global-commands absoiute_directory_name— G ives the name of the system-wide generic commands directory. 
internal-local-commands reiative_directory_name— G ivesthe name ($home relative) of the per-user generic com¬ 
mands directory. 

internal-variable-prefix prefix— G ives the prefix for the configuration environment variables rstartd passes to its 
kids 

INTERNAL-AUTH-PROGRAM authscheme program argv[0] argv[1 ]...—Specifies the program to run to Set Up authentica¬ 
tion for the specified authentication scheme program argv[0] ... gives the program to run and its arguments in the same 
form as the exec keyword. 

internal-auth-input authscheme— Specifiesthe data to be given to the authorization program as its standard input. Each 
argument ispassed as a single line. $n, wheren is a number, is replaced by the nth argument to the auth authscheme argi 
arg2 ... line. 

internal-print arbitrary text— Prints its arguments as a Debug message. M ostly for rstartd debugging, but could be 
used to debug configfiles 





NOTES 

When using theC shell, or any other shell that runs a script every time the shell isstarted, the script may be run several 
times In the worst case the script may be run three times: By rsh, to run rstartd; by rstartd, to run the specified 
command; by the command, such as xte™. 

rstartd currently limits lines both from config files and requests to bufsiz bytes 

detach is implemented by redirecting file descriptors©, i, and 2 to /dev/nuiiand forking before executing the program. 
cmd isimplemented by invoking $shell (default /bin/sh) with -c and the specified command as arguments. 
posix-umask isimplemented in the obvious way. 

The authorization programs are run in the same context asthetarget program— same environment variables path, and so 
on. Longterm, this might beaproblem. 

In thex context, GENERIC-CMD Terminal runsxterm. In theOpenWindows context, GENERIC-CMD Terminal runScmdtool. 

In thex context, generic-cmd LoadMomtor runsxioad. In theopenwindows context, generic-cmd LoadMomtor runs 
perfmeter. 

generic-cmd Listcontexts lists the contents of ©List in both the system-wide and per-user contexts directories Itis 
available in all contexts. 

generic-cmd ListGenericCommands lists the contents of ©List in the system-wide and per-user commands directories 
including the per-context subdirectories for thecurrent context. It isavailable in all contexts 
context None is not implemented. 
context Default is really dull. 

For installation ease the contexts directory in the distribution containsa file ©Aliases, which lists a context name and 
aliases for that context. Thisfileisused to makesymlinksin the contexts and commandsdirectories 
All misc values are passed unmodified as environment variables 

You can mistreat rstartd in any number of ways resulting in anything from stupid behavior to core dumps Other than by 
explicitly running programs, I don't think it can write or delete any files, but there's no guarantee of that. The important 
thing is that (a) it probably won't do anything REALLY stupid and (b) it runs with the user's permissions, so it can't do 
anything catastrophic. 

©List files need not be complete; contexts or commands that are dull or which need not or should not be advertised need 
not be listed. In particular, per-user ©List files should not list thingsthat are in the system-wide ©List files. In thefuture 
perhaps Listcontexts and ListGenericCommands will automatically suppress lines from the system-wide files when there are 
per-user replacements for those lines. 

Error-handling isOK to weak. In particular, no attempt is made to properly report errors on the exec itself. (Perversely, exec 
errors could be reliably reported when detaching, but not when passing the stdin/out socket to theapp.) 

If compiled with -dodti_display_hack, rstartd will work around a bug in sco odt version 1. (1.1?) (The bug isthat thex 
clients are all compiled with a bad library that doesn't know how to look hostnames up using D N S. The fix is to look up a 
hostname in $display and substitute an ip address) T his isa trivial example of an incompatibility that rstart can hide. 

SEE ALSO 

rstart(l), rsh(l), "A Flexible Remote Execution Protocol Based on rsh" 

AUTHOR 

Jordan Brown, Quarterdeck Office Systems 


X Version 11 Release 6 
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r up 

rup— Remote status display 

SYNOPSIS 

rup [-dhlt] [host ...] 

DESCRIPTION 

rup displays a summary of the current system status of a particular host or all hosts on the local network. T he output shows 
the current time of day, how long the system has been up, and the load averages. The load average numbers give the number 
of jobs in the run queue averaged over 1, 5 and 15 minutes. 

Thefollowing options are available: 

-d For each host, report what its local time is This is useful for checking time synchronization on a network. 

- h Sort the display alphabetically by hostname. 

- i Sort the display by load average. 

-t Sort the display by uptime. 

The rpc. rstatd(8) daemon must be running on the remote host for this command to work, rup uses an RPC protocol 
defined in /usr/include/rpcsvc/rstat.x. 

EXAMPLE 

example% rup otherhost 

otherhost up 6 days, 16:45, load average: 0.20, 0.23, 0.18 
example% 

DIAGNOSTICS 

rup: rpc: Program not registered— The rpc. rstatd(8) daemon has not been started on the remote host, 
rup: rpc: Timed out— A communication error occurred. Either the network is excessively congested, or the 
rpc. rstatd(8) daemon has terminated on the remote host. 

rup: RPC: Port mapper failure ■ RPC: Timed out- The remote host isnot running the portmapper (see portmap(8) 
man page), and cannot accommodate any RPC-based services The host may be down. 

SEE ALSO 

ruptime(l), portmap(8), rpc.rstatd(8) 

HISTORY 

The rup command appeared in SunOS. 

BSD 4.3,7Junel993 
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rusers—O utput who is logged in to machines on local network 

SYNOPSIS 

rusers [-al] [host ...] 

DESCRIPTION 

The rusers command produces output similar to who, but for the list of hosts or all machines on the local network. For each 
host responding to the rusers query, the hostname with the names of the users currently logged on is printed on each line. 
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The rusers command will wait for one minute to catch late responders. 

Thefollowing options are available: 

-a Print all machines responding even if no one is currently logged in. 

-l Print a long format listing. This includes the username hostname, tty that the user is logged in to, the date and 
time the user logged in, the amount of time si nee the user typed on the keyboard, and the remote host the user 
logged in from (if applicable). 

DIAGNOSTICS 

rusers: rpc: Program not registered— The rpc. rusersd(8) daemon has not been started on the remote host, 
rusers: rpc: Timed out- A communication error occurred. Either the network is excessively congested, or the 
rpc. rusersd(8) daemon has terminated on the remote host. 

rusers: rpc: Port mapper failure - rpc: Timed out- The remote host is not running the portmapper (see 
portmap(8) for more information), and cannot accommodate any RPC-based services The host may be down. 

SEE ALSO 

rwho(l), users(l), who(l), portmap(8), rpc. rusersd(8) 

HISTORY 

The rusers command appeared in SunOS. 

BUGS 

The sorting options are not implemented. 

BSD 4.2,23 April 1991 


rwall 

rwaii- Send a message to users logged on a host 

SYNOPSIS 

DESCRIPTION 

The rwaii command sends a message to the users logged in to the specified host. The message to be sent can be typed in and 
terminated with EOForitcan be in a file 

DIAGNOSTICS 

rwaii: rpc: Program not registered- The rpc. rwaiid(8) daemon has not been started on the remote host, 
rwaii: rpc: Timed out— A communication error occurred. Either the network is excessively congested, or the 
rpc. rwaiid(8) daemon has terminated on the remote host. 

rwaii: rpc: Port mapper failure - rpc: Timed out- The remote host is not running the portmapper, and cannot 
accommodate any RPC-based services The host may bedown. 

SEE ALSO 

wall(l), portmap(8), rpc.rwalld(8) 

HISTORY 

The rwaii command appeared in SunOS. 


BSD 4.2, 23 April 1991 
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rwho 

rwho- Output who is logged in on local machines 

SYNOPSIS 

DESCRIPTION 

The rwho command produces output similar to who, but for all machineson the local network. If no report has been received 
from amachinefor 11 minutes, then rwho assumes the machine is down, and does not report users last known to be logged 
in to that machine 

If a user hasn't typed to the system for a minute or more then rwho reports this idle time. If a user hasn't typed to the system 
for an hour or more, then the user will be omitted from the output of rwho unless the - a flag isgiven. 

FILES 

/var/rwho/whod.* Information about other machines 

SEE ALSO 

finger(l), rup(l), ruptime(l), rusers(l), who(l), rwhod(8) 

HISTORY 

The rwho command appeared in BSD 4.3. 

BUGS 

This is unwieldy when the number of machineson the local ndt is large. 

BSD 4.2,23 April 1991 


script 

script—M ake typescript of terminal session 

SYNOPSIS 

script [-a] 

DESCRIPTION 

script makes a typescript of everything printed on your terminal. It is useful for students who need a hardcopy record of an 
interactive session as proof of an assignment, as the typescript file can be printed out later with ipr(l). 

If the argument file isgiven, script saves all dialogue in file If no filename is given, the typescript is saved in the file 
typescript. 

Option: 

-a Append theoutput to file or typescript, retaining the prior contents 

The script ends when theforked shell exits (a control -d to exit the Bourne shell, sh(l), and exit, logout, or control-d (if 
ignoreeof isnotset) for the C-shell, csh(l)). 

Certain interactive commands, such asvi(l), create garbage in the typescript file Script works best with commands that do 
not manipulate the screen; the results are meant to emulate a hardcopy terminal. 



ENVIRONMENT 

Thefollowing environment variable is utilized by script: 

shell If the variable shell exists, the shell forked by script will be that shell. If shell is not set, the Bourne shell is 
assumed. (M ost shells set this variable automatically.) 

SEE ALSO 

csh(l) (for the history mechanism) 

HISTORY 

The script command appeared in BSD 3.0. 

BUGS 

script places everything in the log file including linefeeds and backspaces This is not what the naive user expects. 

BSD 4,27 July 1991 


sed 

sed—Stream-oriented editor 

SYNOPSIS 

sed [ -hnV ][-e script ][-f script-file ][--help ][--quiet ][--silent ] 
[--version][- -expressions c ri pt ][--file=s c r i pt - f i I e ] [fiIe ... ] 


DESCRIPTION 

sed reads the specified files or the standard input if no files are specified, makes editing changes according to a list of 
commands and writes the results to the standard output. 


OPTIONS 

-h, - - help 

-n, --quiet, --silent 


-V, - -version 

-e script, -- expressi on=scri pt 




Print a usage message on standard output and exit successfully. 

Suppress the default output, sed only displays linesexplicitly specified for 
output with the p command or the p flag of the s command. The default 
behavior isto echo each line of input, after edits, to the standard output. 
Print the version number on the standard output and exit successfully. 
Append one or more commands specified in the string s c r i pt to the list of 
commands If there is just one -e option and no -f options, the -e flag may 
be omitted. 

Append the editing commandsfromscri pt-fi i e to the list of commands 


Multiple -eand -f commands may be specified. Scripts are added to the list of commands to executein the order specified, 
regardless of their origin. 


USAGE 

OPERATION 

sed operates as follows: 

Each line of input, not including its terminating newline character, is successively copied into a pattern space (a 
temporary buffer). 

All editing commands whose addresses match that pattern space are sequentially applied to thepattern space. 
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When reaching the end of the command list, the pattern space is written to the standard output (except under -n) with 
an appended newline. 

T he pattern space isdeared and the process is repeated for each line in the input. 

With sed, original in put files remain unchanged because editing commands only modify a copy of the input. 

Somesed commands use a hold space to save all or part of the pattern spacefor later retrieval. 

COMMAND SYNTAX 

A sed script consists of commands with the general form: 

[address [, address ] ] [! ] c o mma n d [arguments] 

T ypically, there is only onecommand per line, but commands may also be concatenated on a single line by semicolons 
Whitespace characters may beinserted before the first address and the command portions of thescript command. 

ADDRESSES 

A sed command, as indicated, can specify zero, one, or two addresses An address can be 

A line number, represented in decimal. The internal line number count maintained by sed is cumulative across input 
files and is not reset for each input file 

A pattern that is a regular expression, represented by nc patternc, where c is any character except backslash (\) or 
newline In the address nxabcnxdefx, the second x stands for itself, so the regular expression isabcxdef. However, the 
preferred (and equivalent) method to construct a regular expression isto enclose the pattern in slashes- /pattern/. 
Additionally, \n can be used to match any newlinein the pattern space except for the final newline character. 

A $ character that addresses the last lineof input. 

GNU sed also implements a new type of address The address has form n'm, which matches any line where the line 
number modulo m isequal to n modulo m. If m is oor missing, then i is used in its place. This feature is not specified by 
POSIX. 

The following rules apply to addressed commands: 

A command line with no address selects each input line. 

A command line with one address selects any line matching the address Several commands accept only one address: =, a, 
i, r,and q. 

A command line with two comma-separated addresses selects the first matching line and all following lines up to and 
including the line matching thesecond address If the second address starts before oristhe sameline as thefirst address 
then only thefirst line is selected. 

An addressfollowed by i selects all lines that do not match the address 

REGULAR EXPRESSIONS 

Regular expressions are patterns used in selecting text. For example, the sed command 


prints all lines containings t r i ng. 

In addition to specifying string literals regular expressions can represent classes of strings. Strings thus represented are said to 
be matched by the corresponding regular expression. If it is possible for a regular expression to match several strings in aline, 
then the leftmost longest match is the one selected. 

The following symbols are used in constructing search patterns 

The null regular expression isequivalent to the last regular expression used, 
c Any character c not listed here— including {,>,,, <, >, |, and+-matches itself. 

\c Any backslash-escaped character c, except for {,},,,<,>, j, and +, matches itself. 

■-in 1 . M atches any single character except newline. 



sed ^ 

[char ■ ci ass ] M atches any single character, other than newline in char - cl ass.To include a ] inchar- 

c i a s s, it must be the first character. A range of characters may be specified by separati ng the 
end characters of the range with a for example, a-z specifies the lowercase characters. The 
following literal expressions can also be used in char - ci ass to specify sets of characters: 

[:alnum:] [:cntrl:] [:lower:] [:space:] 

[:alpha:] [:digit:] [:print:] [cupper:] 

[:blank:] [:graph:] [:punct:] [:xdigit:] 

If - appears asthe first or last character ofchar- ci ass, then it matches itself. All other 
characters inchar-ci ass match themselves. 

[ ‘char - ci ass ] M atches any single character, other than newline not in char- ci ass. char - ci ass isdefined 

as in the preceding entry. 

If * isthefirst character of a regular expression, then it anchors the regular expression to the 
beginning of a line. Otherwise it matches itself. 

$ If $ isthe last character of a regular expression, it anchors the regular expression to the end 

of a line Otherwise, it matches itself. 

\<, \> Anchorsthe single character regular expression or subexpression immediately following it to 

the beginning (\<) or ending (\>)of a word, that is, in ASC11, a maximal string of 
alphanumeric characters, including the underscore (_). 

\ (re \) Definesa (possibly null) subexpression re. Subexpressions may be nested. A subsequent 

back reference of the form ■ \n ',wheren isanumberintherangel-9,expandstothetext 
matched by the nth subexpression. For example the regular expression \(a.c\)\i matches 
the string 'abcabc 1 , but not 'abcadc 1 . Subexpressions are ordered relative to their left 
delimiter. 

* M atches the single-character regular expression or subexpression immediately preceding it 

zero or more times. If * isthefirst character of a regular expression or subexpression, then it 
matches itself. The* operator sometimes yields unexpected results. For example the regular 
expression b* matchesthe beginning of the string 'abbb 1 (asopposed to the substring 
■ bbb 1 ) becauseanull match is the only leftmost match. 

\+ M atches the single character regular expression or subexpression immediately preceding it 

oneor more times 

\ | M atches the regular expression or subexpression specified before or after it. 

\{n ,m\} or \{n ,\} or \{n\> M atches the single-character regular expression or subexpression immediately preceding it at 
least n and at most m times. If m isomitted, then it matches at least n times. If the comma is 
also omitted, then it matches exactly n times 

(\ group \) M atches the enclosed group of regular expressions. 

Thefollowing characters only have special meaning when used in replacement patterns: 

\ Escapethefollowing character. 

\n M atches thenth pattern previously saved by n(' and 'n),wheren is a number from 0 to 9. 

Previously saved patterns are counted from the leftmost position on the line. 

& Printsthe entire search pattern when used in a replacement string. 

COMMENTS 

If the first nonwhite character in a line is a#), sed treats that line as a comment, and ignores it. If, however, thefirst such 

lineisoftheform: 


sed runs as if the -n flag were specified. 
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GROUPING COMMANDS 

Braces ({,}) can be used to nest one address within another or to apply multiple commands to the same address: 

[address]!, address]] 
command 1 command 2 ... 


The opening] must end a line and the dosing} must be on a line by itself. 


COMMANDS 

The maximum number of permissible addresses for each command is indicated in parentheses in thefollowing list. 

An argument denoted text consists of one or more lines of text. If text is longer than one line in length, then any newline 
characters must be hidden by preceding them with a backslash (\). 

An argument denoted read-filename or write-filename must terminate the command line and must be preceded by 
exactly one space Each write-filename is created before processing begins. 


(0) 

(0) #comment 
(0) : I abel 


(1 )a\t ext 


(2) c\t ext 


(2) G 



(2) 1 


An empty command is ignored. 

The line is a comment and is ignored by sed. If, however, thefirst such line in a script is of 
theform #n, then sed behaves as if the -n flag had been specified. 

Affix i abei to a linein thescript for a transfer of control by b or t commands. 

W rite the current line number on the standard output as a line 

Append text following each line matched by the address on thestandard output before 

reading the next input line. 

Unconditionally transfer control to the: command bearing the i a be i .If no label is 
specified, then branch to the end of thescript; no more commands are executed on the 
current pattern space. 

Change the pattern space by replacing the selected pattern with t ext . W hen multiple lines 
are specified, all lines in the pattern space are replaced with a single copy of t ext . The end 
result is that the pattern space is deleted and no further editing commands can be applied 
to it. 

D elete the pattern space, preventing the line from being passed to the standard output, and 
start the next cycle 

Delete the initial segment of the pattern space through thefirst newline and start the next 
cycle. 

Replace the contents of thepattern space by the contents of the hold space 

Append a newline character followed by the contents of the hold space to thepattern space. 

Replace the contents of thehold space by the contents of thepattern space 

Append a newline character followed by the contents of the pattern space to the hold space. 

Insert text by writing it to the standard output. 

Write the pattern space to standard output in a visually unambiguous form. Nonprinting 

characters are displayed as either three-digit octal values, preceded by a\, or as one of the 

following character constant escape sequences: 

u Backslash 

\a Alert 

\b Backspace 

\f Form-feed 

\n Newline 

\r Carriage-return 

\t Tab 

\v Vertical tab 
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( 2 ) r read-fi I ename 

(2) s/regul arexpressi on/ 
repl acement /flags 


(2) w wr i t e- f i I ename 
(2) x 


(2) y/stri ngl/stri ng2/ 


Long lines are folded, with the point of folding indicated by a backslash (\) and a newline 
character. The end of every line is marked with a$. 

C opy the pattern space to the standard output. Replace the pattern space with the next line 
of input. 

Append the next line of input to thepattern space with an embedded newline (The current 
linenumber changes.) 

Print the pattern space to the standard output. 

Copy theinitial segment of thepattern space through the first newline to thestandard 
output. 

Quit by transferring control to the end of the script and do not start a new cycle. The 
pattern spaceisstill written to thestandard output. 

Read the contents of read-fi i ename. Place them on the output before reading the next 
input line 

Substitute the r epl acement string for instances of the r egu i ar expression i n the pattern 
space. Any character may be used instead of /. (For a fuller description, see the explanation 
of replacement patterns in the "Regular Expressions" section of this manual page.) flags is 
zero or more of: 

n Substitute for just the nth occurrence of the regular expression, 
g G lobally substitute for all nonoverlapping instances of the regular expression 
rather than just thefirst one. 

p Print the pattern space if a replacement was made. 

Append the pattern space to wr i t e-f i i ename if a replacement was made. 

Branch to the: command bearing thei a be i if any substitutions have been madesincethe 
most recent reading of an input line or execution of at. If i a be i is empty, branch to the 
end of the script. 

Append the pattern space to wr i t e-f i i ename. 

Exchange the contents of the pattern and hold spaces. 

Replace all occurrences of characters in s t r i n g l with the corresponding character i n 
stri n g 2 . T he lengths of s t r i ngi andstri n g 2 must be equal. Any character other than 1 ■ 
or newline can be used instead of slash to delimit the strings Within st ri ngi andstri ng 2 , 
the delimiter itself can be used as a literal character if it is preceded by a backslash. 


DIAGNOSTICS 

command only uses one address— A command that takes one address had two addresses specified, 
command doesn't take any addresses—A command that takes no addresses had an address specified. 

Extra characters after command—A command had extra text after the end. 

unexpected End-of-file— Theend of a script was reached before it should havebeen. This usually occurs when a 
command is started, but not finished. 

no previous regular expression—A metacharacter calling for a previous regular expression before any regular 
expressions were used. 

Missing command— An address was not followed by a command, 
unknown command-A command was not one of the ones recognized by sed. 
unexpected 1 ,A command had a spurious comma after an address 
Multiple ■! ■ s— M ore than one i (exclamation point) was used in acommand. 
unexpected g—A g character was given in a command without a preceding f. 
unexpected f—An f character was given in acommand without a following g. 

} doesn't want any addresses—} should be alone on a line 
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: doesn't want any addresses— The : command should not be preceded by an address. 

unterminated s command— The replacement field of the s command should be completed with a / character. 

Multiple p options to s command — The p option was given more than once in an s command. 

Multiple g options to s command— Theg option wasgiven morethan oncein an s command. 

Multiple number options to s command— M orethan one number option wasgiven to an s command, 
unknown option to s— An unknown option was used for the s command. M aybe you shouldn't do that, 
strings for y command are different lengths— There should be a one-to-one mapping between strings for they 
command. 

Missing ' 1 before filename— There was no space between an r, w, or si //w command, and thefilename specified for 
that command. 

Hopelessly evil compiled in limit on number of open file, re-compile sed .— An attempt Was made to Open 
too many files, no matter how you look at it. 

SEE ALSO 

awk(l), ed(l), grep(l), perl(l), regex(3) 

HISTORY 

A sed command appeared in version 7 AT&T UN IX. 

STANDARDS 

GNU sed is expected to bea superset of the IEEE Stdl003.2 (PO SIX) specification. 

CAVEATS 

GNU sed uses the PO SI X basic regular expression syntax. According to the standard, the meaning of some escape sequences 
is undefined in this syntax; notably \ | and \+. 

As in all G N U programs that use PO SIX basic regular expressions, sed interprets these escape sequences as metacharacters 
So, x\+ matches one or more occurrences of x. abc\ | def matches either abc or def. 

This syntax may cause problems when running scripts written for other versions of sed. Some sed programs have been 
written with the assumption that \ | and \+ match the literal characters j and +. Such scripts must be modified by removing 
the spurious backslashes if they are to be used with GNU sed. 

BUGS 

It has long been noted thatGN U sed is much slower than other implementations The current bottleneck istheway sed 
reads and writes data files It should read large blocks at a time (or even map files where that is supported). When possible it 
should avoid copying its input from one place in memory to another. Patches to make it do those things are welcome! 

Verson 2.05, D ecember 1994 


sessreg 

sessreg— M anageutmp/wtmp entries for non-init clients 

SYNOPSIS 

sessreg [ -w wt mp-f i I e ] [ - u u t mp - f i I e ] [-1 line-name] [-h host ■ name ] 

[ -s si ot ■ number ] [ -x Xservers-fi I e] [-t t-tys-f i I e ] [-a] [-d ] user - name 

DESCRIPTION 

sessreg is a simple program for managing utmp/wtmp entries for xdm sessions. 
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System V has a better interface to /etc/utmp than BSD ; it dynamically allocates entries in the file instead of writing them at 
fixed positions indexed by position in /etc/ttys. 

To manage BSD-style utmp files, sessreg hastwo strategies. In conjunction with xdm, the -x option counts the number of 
li nes in /etc/ttys and then adds to that the number of the line in the xservers file that specifies the display. T he display 
name must be specified as the i i ne - name using the -1 option. This sum is used as the si ot- number in /etc/utmp that this 
entry will be written at. I n the more general case, the - s option specifies the si ot ■ number directly. If for some strange reason 
your system uses a file other that /etc/ttys to manage intt, the -t option can direct sessreg to look elsewhere for a count 
of terminal sessions. 

Conversely, System V managers will never need to use these options (-x, -s,and -t). To make the program easier to 
document and explain, sessreg accepts the BSD -specific flags in the System V environment and ignores them. 

BSD also hasahost ■ name field in the utmp file that doesn't exist in System V. This option isalso ignored by the System V 
version Of sessreg. 

USAGE 

In xstartup, place a call like: 

sessreg -a -1 $DISPLAY -x /usr/X11R6/lib/xdm/Xservers $USER 
and in xreset: 

sessreg -d -1 $DISPLAY -x /usr/X11R6/lib/xdm/Xservers $USER 


OPTIONS 




This specifies an alternate wtmp file instead of /usr/adm/wtmpfor BSD or /etc/wtmpfor sysv. The 
special name none disables writing records to /usr/adm/wtmp. 

This specifies an alternate utmp file instead of /etc/utmp. The special namenone disables writing 
records to /etc/utmp. 

This describes the line name of the entry. For terminal sessions, thisisthefinal pathname segment 
of the terminal device filename (for example, ttydo). For x sessions, it should probably be the local 
display name given to the users session (for example, :©). If none is specified, the terminal name 
will be determined with ttyname(3) and stripped of leading components. 

This is sdt for BSD hosts to indicate that the session was initiated from a remote host. In typical 
xdm usage this options is not used. 

Each potential session has a unique slot number in BSD systems; most are identified by the 
position of thei i ne- name in the /etc/ttys file Thisoption overrides the default position 
determined with ttys-iot(3). Thisoption is inappropriate for use with xdm, the -x option is more 
useful. 

Asxsessionsareoneper-display, and each display is entered in thisfile this options sets the si ot- 
n umber to be the number of lines in thettys-f 11 e plus the index into thisfile that the i i ne- name 
isfound. 

This specifies an alternate filethat the -x option will use to count the number of terminal sessions 
on a host. 

This session should be added to utmp/wtmp. 

This session should be deleted from utmp/wtmp. -a or -d must be specified. 


SEE ALSO 

xdm(l) 

AUTHOR 

Keith Packard, M IT X Consortium 


X Verson 11 Release6 
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setterm 

setterm— Sdt terminal attributes 

SYNOPSIS 

setterm [ -term termi nal name ] 

setterm [-reset ] 

setterm [ -initialize ] 

setterm [ -cursor [on]off] ] 

setterm [ -keyboard pc[Olivetti[dutch]extended ] 

setterm [ -repeat [on]off] ] 

setterm [ -appcursorkeys [on[off] ] 

setterm [ -linewrap [onjoff] ] 

setterm [ -snow [on[off] ] 

setterm [ -softscroll [on[off] ] 

setterm [ -defaults ] 

setterm [ -foreground black[red[green[yellow[blue[magenta[cyan]white]default ] 

setterm [ -background black[red[green[yellow[blue[magenta[cyanjwhite|default ] 

setterm [ -ulcolor black[grey[red|green[yellow[blue[magenta[cyan[white ] 

setterm [ -ulcolor bright red[green[yellow[blue[magenta[cyan[white ] 

setterm [ -hbcolor black[grey[red[green[yellow]blue[magenta]cyan[white ] 

setterm [ -hbcolor bright red[green[yellow[blue[magenta[cyan[white ] 

setterm [ -inversescreen [on]off] ] 

setterm [ -bold [on[off] ] 

setterm [ -half-bright [on[off] ] 

setterm [ -blink [onJoff] ] 

setterm [ -reverse [on[off] ] 

setterm [ -underline [on[off] ] 

setterm [ -store ] 

setterm [ -clear [ all[rest ] ] 

setterm [ -tabs [tabl tab2 tab3 ... ] ] where (tabn = 1-160) 
setterm [ -clrtabs [ tabl tab2 tab3 ... ] where (tabn = 1-160) 




sgitopnm 


483 


setterm [ -regtabs [ 1-160 ]] 
setterm [ -blank [ 0-60 ]] 
setterm [ -dump [ 1 - NR CONS ]] 
setterm [ -append [ 1 -NR CONS ]] 
setterm [ -file dumpfilename ] 
setterm [ -standout [ at t r ]] 

DESCRIPTION 

setterm writes to standard output a character string that will invoke the specified terminal capabilities. Where possible, / 
etc/termcap is consulted to find the string to use. Some options, however, do not correspond to atermcap(5) capability. In 
thiscase, if the terminal type is minix -vc or minix -vcam, the string that invokes the specified capabilities on the PC M i nix 
virtual console driver is output. Options that are not implemented by the terminal are ignored. 

OPTIONS 

M ost options are self-explanatory. T he less obvious options are as follows: 

-term Can beused to overridetheTERMenvironment variable 

-reset D isplays the terminal reset string, which typically resets theterminal to its power on state 

-initialize D isplays the terminal initialization string, which typically sdts the terminal's rendering options, and other 
attributes to the default values 

-default Setstheterminal's rendering optionsto the default values 
-store Stores the terminal's current rendering options as the default values 

L inux 0.98, 25 D ecember 1992 

SEE ALSO 

tput(l), stty(l), termcap(5), tty(4) 

BUGS 

D ifferences between the M inix and Linux versionsare not documented. 

AUTHORS 

Gordon Irlam (gordoni@cs.ua.oz.au); adaptation to Linux by Peter M acDonald; enhancements by M ika Liljeberg 

(liljeber@cs.Helsinki.Fl) 

L inux 0.98, 25 D ecember 1992 


sgitopnm 

sgitopnm- Convert an SGI image file to a portable anymap 

SYNOPSIS 

sgitopnm [-verbose][SGI file] 

DESCRIPTION 

ReadsanSGI imagefile as input. Producesa PGM image for a two-dimensional (one-channel) inputfile, and aPPM image 
for a three-dimensional (three or more channels) inputfile. 
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OPTIONS 

-verbose Givesomeinformation about the SGI imagefile 

BUGS 

Probably 

REFERENCES 

SGI Image File Format documentation (draft v0.95) byPaul Haeberli (paui@sgi.com). Available viaftp at 
sgi.com:graphics/SGIIMAGESPEC. 

SEE ALSO 

pnm(5), pnmtosgi(l) 

AUTHOR 

Copyright® 1994 by Ingo W i I ken (lngo.Wilken@informatik.uni-oldenburg.de). 

29 January 1994 


shan 

shar- Create shell archives 

SYNOPSIS 

shar [ options ] file ... 
shar -S [ opti ons ] 

DESCRIPTION 

shar creates shell archives (or shar files) that are in text format and can be mailed. These files may be unpacked later by 
executing them with /bin/sh. The resulting archive issent to standard out unless the -o option isgiven. A wide range of 
features provide extensive flexibility in manufacturing sharsand in specifying shar "smartness." Archives may be "vanilla" or 
comprehensive This manual page reflects shar version 4.0. 

OPTIONS 

Options have a one-ldtter version starting with - or a long version starting with --.The exceptions are --help and -- 
version, which do not have short versions. Options can be given in any order. Some options depend on each other: The - o 
option is required if the -l or -l option is used. 

The -n option isrequired if the -a option isused. 

See -v in thefollowing list. 

T hese are the available options 

--version 
--help 

-V, - -vanilla-operation 


Print the version number of the program on standard output, then immedi¬ 
ately exit. 

Print a help summary on standard output, then immediately exit. 

Produce vanilla sharsthat rely only upon the existence of sed and echo in 
the unsharing environment. In addition, if test must also be supported if 
the -x option isused. The-v silently disables options offens've to the 
network cop (or brown shirt), but does warn you if it is specified with -b, - 
z, -z, -p, or -m (any of which doesor might require uudecode, gzip or 
compress in the unsharing environment). 
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- -no-verbose 

- -no-character-count 
name, --archive-name=n a me 

- -net-headers 


who@where, - -submitter=who@where 

- -no-check-existing 

- -query-user 

- -uuencode 


- -compress 

- -no-timestamp 

- - intermix-type 

X, --level-for-gzip=X 
X, - - bits-per-code=X 


Verbose off. disables the inclusion of comments to be output when the 
archive is unpacked. 

Do NOT check with wo -c after unpack. The default is to check. 

Name of archive to be included in the header of the shar files. (Seethe - a 
switch.) 

Allows automatic generation of headers: 

Submitted by: whoOwhere 
Archive-name: <name>/part## 

T he <n a me > must be given with the -n switch. If name includes a /.then / 

part isn't used. Thus -n xyzzy producesthefollowing: 

xyzzy/partOI 

xyzzy/part02 

-n xyzzy/patch produces the following: 

xyzzy/patch01 

xyzzy/patch02 

-n xyzzy/patchoi . produces the following: 
xyzzy/patch01.01 
xyzzy/patch01.02 

Thewho@wherecan be explicitly stated with the -s switch if the default isn't 
appropriate who@where isessentially built as , whoami , <a , uname'. 

Override automatically determined submitter name. 

Overwrite existing files without checking. If neither -x nor -x is specified, the 
unpack will check for and not overwrite existing files when unpacking the 
archive (unless -c is passed as a parameter to the script when unpacking). 
Interactively overwrite existing files (D o not use for shars submitted to the 
N et.) 

T reatall files as binary; use uuencode prior to packing. Thisincreasesthesize 
of the archive. T he recipient must have uudecode in order to unpack. (U se of 
uuencode is not appreciated by many on the N et.) 

T reat all files as text (default). 

Usegzip and uuencode on all files prior to packing. The recipient must have 
uudecode and gzip (used with -d) in order to unpack. (Useof uuencode and 
gzip is not appreciated by many on the N et.) 

U se compress and uuencode on all files prior to packing. T he recipient must 
have uudecode and compress (used with -d) in order to unpack. (Use of 
uuencode and compress is not appreciated by many on the Net.) Option -c 
is synonymous to -z, but is being depreciated. 

Avoid generating touch commands to restore thefile modification dates 
when unpacking files from the archive 

Allow positional parameter options. The options -b, -t, -z, and -z may be 
embedded, and files to the right of the option will be processed in the 
specified mode 

When doing compression, use -x as a parameter to gzip. The -g option 
turns on the -z option by default. 

When doing compression, use -bx as a parameter to compress The -b option 
turns on the -z option by default. 
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l-uuencode 




! --output-prefix=XX 


- -whole-size-limit=XX 
--split-size-limit=XX 


M ixed mode. D dtermi ne if the files are text or binary and archive correctly. 
Files found to be binary are uudecoded prior to packing. (Use of uuencodeis 
not appreciated by many on the N et.) 

U se temporary files instead of pipes in the shar file. 

Start the shar with a cut line. A line saying cut here is placed at the start of 
each output file. 

Restore by filename only, rather than path. Thisoption causes only filenames 
to be used, which is useful when building a shar from several directories, or 
another directory. N otethat if a directory name is passed to shar, the 
substructure of that directory will be restored whether -f isspecified or not. 
Usexxx to delimitthefilesin theshar instead of shar_eof. Thisisfor those 
who want to personalize their shar files. 

Forcesthepref i * character (normally xunlessthe parameter to the-d 
option starts with x) to be prepended to every line even if not required. This 
option may slightly increase the sizeof the archive, especially if -Bor -z is 
used. 

Save the archive to filesxxx .01 through xxx.nn instead of standard out. 

M ust be used when the -1 or the -l switches are used. 

Limit the output file size to xxk bytes, but don't split input files 
Limit output file size to xxk bytes and split files if necessary. The archives 
created with thisoption must be unpacked in correct order. 

Read list of files to be packed from the standard input rather than from the 
command line. Input must be in a form similar to that generated by the 
find command, one filename per line This switch isespecially useful when 
thecommand line will not hold the list of files to be packed. For example: 

find . -type f -print | sort | shar -S -Z -L50 -o /tmp/big 
If-pis specified on the command line then the options -b, -t, -z, and -z 
may beinduded in the standard input (on a line separate from filenames). 
The maximum number of lines of standard input, filenames, and options 
may not exceed 1024. 


EXAMPLES 

shar *.c > cprog.shar # all C prog sources 

shar -v *.[ch] > cprog.shar # non-verbose, .c and .h files 

shar -B -128 -oarc.sh *.arc # all binary .arc files, into 

# files arc.sh.01 thru arc.sh.NN 

shar -f /lcl/src/u*.c > u.sh # use only the filenames 

WARNINGS 

No chmod or touch is ever generated for directories created when unpacking. Thus, if a directory is given to shar, the 
protection and modification dates of corresponding unpacked directory may not match those of the original. 

If a directory is passed to shar, it may be scanned more than once T herefore one should be careful not to change the 
directory while shar is running. 

Becareful that the output file(s) are not included in theinputsor shar may loop until thedisk fills up. Be particularly careful 
when a directory is passed to shar that the output files are not in that directory (or a subdirectory of that directory). 

Use of the -b, -z, or -z, and especially -m, may slow the archive process considerably, depending on the number of files 
Use of -x produces shars that will cause problems with many unshar procedures Usethisfeature only for archivesto be 
passed among agreeable parties Certainly, -x is not for shell archives that are to be submitted to Usenet. Usage of -b, -z, or 
-z in Net shars will cause you to be flamed off theearth. Not using -mor not us'ng -f may also gdtyou occasional 
complaints 
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SEE ALSO 

unshar(l) 

DIAGNOSTICS 

There are error messages for illegal or incompatible options; for nonregular, missing, or inaccessible files; or for (unlikely) 
memory allocation failure 

AUTHORS 

shar(3) is a derived work based on the efforts of the following: JamesGoslingatCM U (decvaximicrosof !uw-beave! jim), 

M ichael A. Thompson, DalhousieUniversity, Halifax, N .S., Canada, Bill Davidsen (davidsen@sixhub), Richard H. 
Gumpertz (rhg@cps.coM), ColasNahaboo (coias@avahi.inria.fr), Bill Aten (biii@netagw.com), DennisBoylan 
(dennis%nanovx@gatech.edu), W arren T ucker (wht%n4hgf@gatech.edu), and other anonymous persons Jan Djfrv 
(j hd@irf u. se) created the man pages. 

27 September 1990 


shlock 

shiock— C reate lock files for use in shell scripts 

SYNOPSIS 

shlock -p pi d -f name [ -b ][-u ][-c ] 

DESCRIPTION 

shiock tries to create a lock file named name and write the process ID pi d into it. If thefile already exists shiock will read 
the process ID from the file and test to see if the process is currently running. If the process exists then the file will not be 
created. 

shiock exits with a zero status if it was able to create the lock file, or non-zero if thefile refers to the currently active process. 
ProcessIDsare normally read and written in ASCII. If the -b flag is used, then they will be written as a binary int. For 
compatibility with other systems the -u flag is accepted as a synonym for -b because binary locks are used by many uucp 
packages. 

Thefollowing example shows how shiock would be used within a shell script: 

LOCK=/news/lib/LOCK.send 
trap 'rm -f ${LOCK} ;exitl 1 1 2 3 15 
if shlock -p $$ -f ${LOCK} ; then 
# Do appropriate work 

echo Locked by 'cat ${LOCK}' 

If the -cflag is used, then shiock will not create a lock file but will instead use the file to see if the lock is held by another 
program. If the lock is valid, the program will exit with anon-zero status; if the lock is not valid (that is, invoking shiock 
without theflag would have succeeded), then the program will exit with a zero status. 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) after a description ofHDBUUCP locking given by Pdter H oneyman. 
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showrgb 

showrgb—Uncompile an RGB colorname database 

SYNOPSIS 

showrgb [ database ] 

DESCRIPTION 

The showrgb program reads an RGB colorname database compiled for use with the dbm database routines and converts it 
back to source form, printing the result to standard output. The default database is the one that x was built with, and maybe 
overridden on the command line Specify the database name without the .pag or .dir suffix. 

FILES 

<xRoot>/iib/xii/rgb D efault database 


X Version 11 Release 6 


shrinkfile 

shrinkf He— Shrink a fileon a lineboundary 

SYNOPSIS 

shrinkfile [ -s size ][-v ] file... 

DESCRIPTION 

The shrinkfile program shrinks files to a given size preserving the data at the end ofthefile T runcation is performed on 
lineboundaries, where a line isa series of bytesending with a newline, \n. T here is no line length restriction and files may 
contain any binary data. 

T emporary files are created in the /tmp directory. The tmpdir environment variable may be used to specify a different 
directory. 

A newline will be added to any nonempty file that does not end with a newline. The maximum file size will not be exceeded 
bythisaddition. 

By default, files are truncated to zero bytes. The -s flag may be used to changethe maximum size. Because the program 
truncatesonly on lineboundaries, thefinal size may be may be smaller then the specified maximum. The size parameter 
may end with a k, m, or g, indicating kilobyte (1024), megabyte (1048576) or gigabyte (1073741824) lengths. Uppercase 
letters are also allowed. The maximum file size is 2147483647 bytes. 

If the -vflagisused, then shrinkfile will print a status line if a file wasshrunk. 

HISTORY 

Written by Landon Curt Noll (chongo@toad.com) and Rich $alz (rsaiz@uunet.uu.net) for InterN dtNews. 

sirtopnm 

sirtopnm— Convert a Solitaire file into a portable anymap 

SYNOPSIS 

sirtopnm [si rfiI e] 
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DESCRIPTION 

Reads a Solitaire Image Recorder file as input. Produces a portable anymap as output. The type of the output file depends on 
the input file; if it’s an MGI TYPE 17 file a pgm file is written. If it’s an MGI TYPE 11 file a ppm file is written. The 
program tells you which type it is writing. 

SEE ALSO 

pnmtosir(l), pnm(5) 

AUTHOR 

Copyright© 1991 by M arvin Landis. 

20 March 1991 


size 

size— List section sizes and total size 

SYNOPSIS 

size [ -A | -B | --formatsompat i bi I i ty ] [--help ] 

[ -d I -o ! -X ! --radix=number ] 

[ --target=bfd n a me ][-V | --version ] objfile ... 

DESCRIPTION 

TheGN U size utility liststhe section sizes and the total size for each of the object files obj file in its argument list. By 

default, one line of output isgenerated for each object file or each modulein an archive. 

OPTIONS 

-A, -B, --format compatibility 




-V, --version 

SEE ALSO 

binutiis entry in info ;TheGNU BinaryUtilities, RolandH. Pesch (October 1991); ar(l), objdump(l) 

COPYING 

Copyright© 1991 Free Software Foundation, Inc. Permission isgranted to make and distribute verbatim copies of this 
manual, provided the copyright notice and this permission notice are preserved on all copies 
Permission isgranted to copy and distribute modified versions of this manual under the conditionsfor verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to thisone. 


U sing one of these options, you can choose whether the output from G N U size 
resembles output from System V size (using -a, or - -format=sysv ), or Berkeley 
size (using -b or - -format=berkeiey) . The default istheone-lineformat similar to 
Berkeley's. 

Show a summary of acceptable arguments and options 
Using one of these options, you can control whether the size of each section is given 
in decimal (-d, or --radix 10 ); octal <-o, or --radix s); or hexadecimal (x , or 
--radix i6). In --radix number, only the three values (8, 10 , i6) are supported. 
Thetotal size is always given in two radices: decimal and hexadecimal for -d or -x 
output, or octal and hexadecimal if you're using -o. 

You can specify a particular object-code format for objfile as bf dname . This may 
not be necessary; size can automatically recognize many formats. (Seeobjdump(l) 
for information on listing available formats.) 

Display version number information on size itself. 
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Permission isgranted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in theoriginal English. 

CygnusSupport, 5 N ovemberl991 


sldtoppm 

sidtoppm- Convert an AutoCAD slide file into a portable pixmap 

SYNOPSIS 

sldtoppm [-adjust][-dir][-height|-ysize s ][-info][-lib|-Lib name] [-scale s] 
[-verbose][-width]-xsize s][slidefile] 


DESCRIPTION 

sldtoppm reads an AutoCAD slide file and outputs a portable pixmap. If no siidefiie is specified, input isread from 
standard input. The ppmdraw library isused to convert the vector and polygon information in the slide file to a pixmap; see 
the file ppmdraw. h for details on this package. 


OPTIONS 


-height size 




If the display on which the slide file was created had nonsquare pixels, when the slide is processed with 
sldtoppm andthe-adjust option is not present, thefollowing warning will appear; warning - pixels on 
source screen were non-square. 

Specifying -adjust will correct image width to compensate. Specifying the - adjust option causes 
sidtoppm to scale the width of the image so that pixels in the resulting portable pixmap are square (and 
hence circles appear as true circles, not ellipses). The scaling is performed in the vector domain, before 
scan-converting the objects The results are, therefore, superior in appearance to what you'd obtain were 
you to perform theequivalent scaling with pnmscaie after the bitmap had been created. 

The input is assumed to be an AutoCAD slide library file. A directory listing each slide in the library is 
printed on standard error. 

Scales the image in the vector domain so it issi ze pixels in height. If no -width or -xsize option is 
specified, the width will be adjusted to preserve the pixel aspect ratio. 

Dump the slide file header on standard error, displaying theoriginal screen size and aspect ratio among 
other information. 

Extracts the slide with the given name from theslide library given asinput. The specified name isconverted 
to uppercase. 

Extracts the slide with the given name from theslide library given asinput. Thename is used exactly as 
specified; it is not converted to uppercase. 

Scales the image by factors, which may be any floating-point value greater than zero. Scaling is done after 
aspect ratio adjustment, if any. Because scaling is performed in the vector domain, before rasterization, the 
results look much better than running theoutput of sidtoppm through pnmscaie. 

Dumps the slide file header and lists every vector and polygon in the file on standard error. 

Scales the image in the vector domain, so it is size pixels wide If no -height or -ysize option is 
specified, the height will be adjusted to preserve the pixel aspect ratio. 

Scales the image in the vector domain so it is si ze pixels wide. If no -height or -ysize option isspecified, 
the height will be adjusted to preserve the pixel aspect ratio. 

Scales the image in the vector domain so it issi ze pixels in height. If no -width or -xsize option is 
specified, the width will be adjusted to preserve the pixel aspect ratio. 


All flags can be abbreviated to their shortest unique prefix. 
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BUGS 

Only Level 2 si ides are con verted. Level 1 format has been obsolete since theadvent of AutoCAD Release 9 in 1987 and was 
not portable across machine architectures 

Slide library itemswith names containing 8-bit (such as I SO) or 16-bit (Kanji, for example) characters may not be found 
when chosen with the - lib option unless sidtoppm has been built with character set conversion functions appropriate to the 
locale You can always retrieve slidesfrom libraries regardless of the character set by using the -Lib option and specifying the 
precise name of library member. Use the -dir option to list the slidesin a library if you're unsure of the exact name. 

SEE ALSO 

AutoCAD ReferenceM anual: "Slide File Format"; pnmscaie(l), ppm(5) 

AUTHOR 

John Walker 
Autodesk SA 

Avenue desChamps-M ontantsl4b 
CH-2074 MARIN 

SuissefSchweiz/ Svizzera/ Svizra/ Swi tzerland 
Usenet: kelvin@Autodesk.com 

Fax: 038/33 88 15 

Voice 038/33 76 33 

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is 
hereby granted, without any conditions or restrictions. T hissoftware is provided "as is" without express or implied warranty. 
AutoCAD and Autodesk are registered trademarks of Autodesk, Inc. 

10 October 1991 


smproxy 

smproxy—Session M anager Proxy 

SYNOPSIS 

smproxy [-clientld id] [-restore saveFiI e ] 

OPTIONS 

-oiientid id Specifies the session ID used by smproxy in theprevioussession. 

-restore saveFiie Specifies the file used by smproxy to save state in theprevioussession. 

DESCRIPTION 

smproxy allowsx applications that do not support X11R6 session management to participate in an X11R6 session. 

In order for smproxy to act asa proxy for an x application, oneof thefollowing must be true: 

■ The application maps a top-level window containing the wm_client_leader property. This property provides a pointer 
to the client leader window that containsthewM_cLAss, wm_name, wm_command, and wm_client_machine properties 

or 

■ Theapplication maps a top-level window that does not contain thewM_ci_iENT_LEADER property. Flowever, thistop-level 
window containsthewM_CLAss, wm_name, wm_command, and wm_client_machine properties 
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An application that supports the wm_save_yourself protocol will receive a wm_save_yourself client message each time the 
session manager issues a checkpoint or shutdown. This allows the application to save state. If an application does not 
support thewM_SAVE_YOURSELF protocol, then the proxy will provide enough information to the session manager to restart 
the application (using wm_coi*iand), but no state will be restored. 

SEE ALSO 

xsm(l) 

AUTHOR 

Ralph Mor, X Consortium 

X Version 11 Release 6 


sort 

sort- Sort lines of text files 

SYNOPSIS 

sort [-emus] [-t separator] [ -o out put-fiIe ] [-T tempdi r ] [ -bdfiMnr] 

[+P0S1 [-P0S2]] [-k P0S1 [,P0S2]] [file...] 
sort {■-help,--version} 

DESCRIPTION 

This manual page documents the GN U version of sort, sort sorts, merges, or compares all the lines from the given files, or 
thestandard input if no files are given. A filename of - means standard input. By default, sort writes the results to the 
standard output. 

sort has three modes of operation: sort (thedefault), merge and check for sortedness. Thefollowingoptionschangethe 
operation mode: 

-c Check whether the given files are already sorted; if they are not all sorted, print an error message and exit with a 
status of i. 

-m M erge the given files by sorting them as a group. Each input file should already be individually sorted. It always 
works to sort instead of merge; merging isprovided because it isfaster, in the case where it works. 

A pair of lines is compared as follows: if any key fields have been specified, sort compares each pair of fields, in the order 
specified on the command line according to the associated ordering options, until a difference is found or no fields are left. 
If any of the global optionsMbdfinr are given but no key fields are specified, sort compares the entire lines according to the 
global options. 

Finally, as a last resort when all keys compare equal (or if no ordering options were specified at all), sort compares the lines 
byte by byte in machine collating sequence. The last resort comparison honors the -r global option. The -s (stable) option 
disables this last-resort comparison so that lines in which all fields compare equal are left in their original relative order. If no 
fields or global options are specified, -s has no effect. 

GNU sort has no limitson input line length or restrictions on bytesallowed within lines. In addition, if the final byte of an 
input file is not a newline, GNU sort silently suppliesone 

If the environment variable tmpdir is set, sort uses it as the directory in which to put temporary files instead of the default, 
/tmp. The -t tempdtr option isanother way to select thedirectory for temporary files; itoverridestheenvironment 
variable 

T he following options affect the ordering of output lines. T hey may be specified globally or as part of a specific key field. If 
no key fields are specified, global options apply to comparison of entire lines; otherwise, the global options are inherited by 
key fields that do not specify any special options of their own. 
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-b Ignore leading blankswhen finding sort keysin each line. 

-d Sort in phone directory order; ignore all characters except letters, digits, and blanks when sorting. 

-t Fold lowercase characters into the equivalent uppercase characters when sorting so that, for example, b issorted 

the same way b is. 

-i IgnorecharactersoutsidetheASCII range040-0176octal (inclusive) when sorting. 

-m An initial string, consisting of any amount of whitespace followed by three letters abbreviating a month name is 
folded to uppercaseand compared in theorder 'jan' < 'feb 1 < ... < 'dec. Invalid namescomparelowto 
valid names. 

-n Compare according to arithmetic value an initial numeric string consisting of optional whitespace an optional - 
sign, and zero or more digits, optionally followed by a decimal point and zero or more digits 
- r Reverse the result of comparison, so that lines with greater key values appear earlier in the output instead of later. 


Other options are 


-t separator 


+POS1 [ -P0S2] 


-k POS1[,P0S2] 


W rite output to o u t p u t - f i i e instead of to the standard output. If output- f i i e isone of the input 
files sort copies it to a temporary file before sorting and writing the output to out put-f i i e. 

U se character separator as the field separator when finding the sort keys in each line By default, 
fields are separated by the empty string between a nonwhitespace character and a whitespace 
character. That is to say, given the input line foo bar, sort breaks it into fields too and bar.The 
field separator is not considered to be part of either the field preceding or the field following it. 

For the default case or the -m option, only output the first of a sequence of lines that compare 
equal. For the -c option, check that no pair of consecutive linescompares equal. 

Specify afield within each line to use asa sorting key. Thefield consists of the portion of the line 
starting at posi and up to (but not including) pos 2 (or to the end of the line if pos 2 is not given). 
The fields and character positions are numbered starting with 0 . 

An alternate syntax for specifying sorting keys T he fields and character positions are numbered 
starting with 1 . 


A position hastheform f .c, wheret is the number of the field to use and c isthe number of thefirst character from the 
beginning of the field (for+pos) or from the end of the previous field (for -pos). The .c part of a position may be omitted, 
in which case it is taken to be the first character in thefield. If the -b option has been given, the .c part of afield specifica¬ 
tion is counted from thefirst nonblank character of thefield (for +pos) or from thefirst nonblank character following the 
previousfield (for -pos). 

A +posor -pos argument may also haveany of the option letters Mbdfinr appended to it, in which case the global ordering 
options are not used for that particular field. The -b option may be independently attached to either or both ofthe+pos and 
-pos parts of afield specification, and if it is inherited from the global options, it will be attached to both. If a -n or -m 
option is used, thus implying a -b option, the-b option istaken to apply to both the+pos and the -pos parts of a key 
specification. Keys may span multiple fields 

In addition, when GN U join isinvoked with exactly one argument, the following optionsare recognized: 

- - help Print a usage message on standard output and exit successfully 

- -version Print version information on standard output, then exit successfully 


COMPATIBILITY 

H istorical (BSD and System V) implementations of sort havediffered in their interpretation of someoptions particularly 
-b, -t,and -n. GNU sort follows the PO SIX behavior, which isusually (but not always) liketheSystem V behavior. 
According to POSIX, -n no longer implies -b. For consistency, -m has been changed in the same way. This may affect the 
meaning of character positionsin field specifications in obscure cases If this bites you, thefix is to add an explicit -b. 

BUGS 

The different meaning of field numbers depending on whether -k isused is confusing. It's all POSIX’sfault! 

GNU Text Utilities 
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spctoppm 

spctoppm- Convert an Atari compressed Spectrum file into a portable pixmap 

SYNOPSIS 

spctoppm [spcfi I e] 

DESCRIPTION 

spctoppm reads an Atari compressed Spectrum file as input and produces a portable pixmap as output. 

SEE ALSO 

sputoppm(l), ppm(5) 

AUTHOR 

Copyright© 1991 by Steve Belczyk (seb3@gte.com) and Jef Poskanzer. 

19 July 1990 


split 

split- Split a file into pieces 

SYNOPSIS 

split [-lines] [-1 lines] [-b byt es [bkm] ] [-C bytes [bkm] ] [ --lines=l i nes ] 

[--bytes=bytes[bkm]] [- - line -bytes=byt e s[bkm]] [--help] [--version] 

[inflie [outfile-prefix]] 

DESCRIPTION 

This manual page documents the GN U version of split, split creates one or more output files (as many as necessary) 
containing consecutive sections of the infiie, or the standard input if noneisgiven or the name - isgiven. By default, 
spilt puts 1000 lines of the input file or whatever is left if it is less than that, into each output file. 

Theoutput filenames consist of a prefix followed by a group of letters, chosen so that concatenating the output files in sorted 
order by filename produces the original input file in order. The default output filename prefix is x. If the outfile-prefix 
argument isgiven, it is used as the output filename prefix instead. 

OPTIONS 

-i i nes, -i 11 nes, --iines=i i nes Puti i nes lines of the input file into each output file 

-b bytes [bkm], --bytes=byt es [bkm] Putbytes bytes of the input file into each output file bytes isanon-zero 

integer, optionally followed by one of the following characters to specify a 
different unit: 
b 512-byte blocks 

k 1-kilobyte blocks 

m 1-megabyte blocks 

-c bytes [bkm], --iine-bytes=byt es [bkm] Put into each output file asmany complete linesof the input file as is 

possible without exceeding bytes bytes If a linethat is longer than bytes 
bytes occurs, put bytes bytes of it into each output file until less than b y t e s 
bytes of the line are left, then continue normally, bytes has the same format 
asforthe--bytes option. 
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Print a usage message and exit with a non-zero status 
Print version information on standard output then exit. 


GNU Text Utilities 


spottopgm 

spottopgm—Convert SPOT satellite images to portable graymap format 

SYNTAX 

spottopgm [ -11213] [Firstcol Firstline Lasted Lastline] inputfile 

OPTIONS 

-i ] 2 ] 3 Extract the given color from the SPOT image The colors are infrared, visible 

light, and ultra-violet, although I don't know which corresponds to which 
number. If the image is in color, this will be announced on standard error. 
The default color is i. 

Firstcol Fi rst i i ne Last col Lastline Extract the specified rectangle from the SPOT image. M ost SPOT images are 
3,000 lines long and 3,000 or more columns wide. Unfortunately, the SPOT 
format only gives the width and not the length. The width is printed on 
standard error. The default rectangle is the width of the input image by 3,000 
lines. 


DESCRIPTION 

spottopgm converts the named inputfile into portable graymap format, defaultingto thefirst color and the whole SPOT 
image unless specified by theoptions. 

INSTALLATION 

You must edit the source program and either define bigendian or littleendian, and fix the typedef s for uint32t, 
uinti 6t, and uint8t appropriately. 


BUGS 

Currently, spottopgm doesn't determine the length of the input file; thiswould involve two passes over the input file. It 
defaults to 3,000 lines instead. 

spottopgm could extract a three-color image (ppm), but I didn't feel like making the program more complicated than it is 
now. Besides, there is no one-to-one correspondence between red, green, blue, and infra-red, visible and ultra-violet. 

I've had only a limited number of SPOT images to play with, and therefore wouldn't guarantee that this will work on any 
other images 

AUTHOR 

W amen Toomey (wkt@csadfa. cs. adfa. oz. au) 

SEE ALSO 

T he rest of the pbmpius suite. 

sputoppm 

sputoppm-Convert an Atari uncompressed Spectrum file into a portable pixmap 
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SYNOPSIS 

sputoppm [spufi I e] 

DESCRIPTION 

sputoppm reads an Atari uncompressed Spectrum file as input and produces a portable pixmap asoutput. 

SEE ALSO 

spctoppm(l), ppm(5) 

AUTHOR 

Copyright© 1991 by Steve Belczyk (seb3@gte.com) and Jef Poskanzer. 

19 July 1990 


sq 

sq— Squeeze a sorted word list 
unsq — U nsqueeze a sorted word list 

SYNOPSIS 

sq < i nfi I e > outfi I e 

DESCRIPTION 

sq compresses a sorted list of words (a dictionary). For example, 

sort /usr/dict/words | sq | compress > words.sq.Z 

will compress diet by about a factor of 4. 

unsq uncompresses the output of sq. For example 

compress -d < words.sq.Z | unsq \ sort -f -o words 

will uncompressa dictionary compressed with sq. The squeezing is achieved by eliminating common prefixes and replacing 
them with a single character that encodes the number of characters shared with the preceding word. The prefix size is 
encoded as a single printable character: 0-9 represent 0-9, A-Z represent 10-35, and a-z represent 36-61. 

AUTHOR 

M ikeWexler 

SEE ALSO 

compress(l), sort(l). 

Local 


startx 

startx—Initialize an x session 

SYNOPSIS 

startx [[client ] options ..] [-- [ server ] options ... ] 




startx 


DESCRIPTION 


NOTE 


The startx script supplied with the X11 distribution is a sample designed more as a base for customization than as a fin¬ 
ished product. Site administrators are urged to customize it for their site- and to update this manual page when they do. 


The startx script isafront end to ximt that provides a somewhat nicer user interface for running a single session of the X 
W indow System. It istypically run with no arguments 

To determine the client to run, startx first looks for afilecalled .xinitrc in the user's home directory. If that is not found, 
it uses the file xinitrc in thexinit library directory. If command-line client options are given, they override this behavior. 
To determine the server to run, startx first looksfor a file called .xserverrc in the user's home directory. If that is not 
found, it uses thefile xserverrc in thexinit library directory. If command-line server options are given, they override this 
behavior. Users rarely need to provide a .xserverrc file. (Seethe xinit(l) manual page for more details on the arguments) 
The .xinitrc istypically a shell script that starts many clients according to the user's preference When this shell script exits 
startx kills the server and performsany other session shutdown needed. M ost of the clients started by .xinitrc should be 
run in the background. The last client should run in the foreground; when it exits, the session will exit. Peopleoften choosea 
session manager, window manager, or xterm as the "magic" client. 

EXAMPLE 

Following is a sample xinitrc that starts several applications and leaves the window manager running as the "last" applica¬ 
tion. Assuming that thewindow manager has been configured properly, the user then chooses the Exit menu item to shut 
down x. 

xrdb -load $HOME/.Xresources 
xsetroot -solid gray & 
xbiff -geometry -430+5 & 
oclock -geometry 75x75-0-0 & 
xload -geometry -80-0 & 
xterm -geometry +0+60 -Is & 

xconsole -geometry -0+0 -fn 5x7 & 


ENVIRONMENT VARIABLES 

display Thisvariablegetssettothenameofthedisplaytowhichclientsshould connect. N ote that this gets set, notread. 


FILES 


$(HOME)/.xinitrc 
$(HOME)/.xserverrc 
<XRoot>/lib/X11/xinit/xinitrc 

<XRoot>/lib/X11/xinit/xserverrc 


Client to run. T ypically a shell script that runs many programs in the background. 
Server to run. T he default is x. 

Client to run if the user has no .xinitrc file. <xRoot>referstotherootoftheXll 
install tree. 

Client to run if the user has no. xserverrc file. This is only needed if the server 
needs special arguments or is not named. <xRoot> refers to the root of the X11 
install tree. 


SEE ALSO 

xinit(l) 


X Version 11 Release 6 
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strings—Print the strings of printable characters in files 

SYNOPSIS 

strings [ - a|-1- - all ][-f \ --print-file-name][-o ][- - help ][-v]■-version ] 

[ -n min-len |-min-len |--bytes= min-len ][-t o, x, d ] 

[ - -target=b f d n a me ] |- -radix= o, x, d ] file 

DESCRIPTION 

For each f i ie given,GNU strings printsthe printable character sequences that are at least four characters long (or the 
number given with the options below) and are followed by aNUL or newline character. By default, it only prints the strings 
from the initialized data sectionsof object files; for other types of files, it prints the strings from the whole file, 
strings is mainly useful for determining the contents of nontext files. 

OPTIONS 

The long and short forms of options, shown here as alternatives, are equivalent. 

-a, - -an, - Donotscanonlytheinitializeddatasectionofobjectfiles;scanthewhole 

files 

-f, --print-file-name Print the name of the file before each string. 

- -help Printasummary of theoptionsto stringson thestandard output and exit. 

-v, - -version Print the version number of stringson thestandard output and exit. 

-n mi n -1 e n, - mi n -1 e n, -bytes=mi n- 1 en Print sequences of characters that are at least mi n- 1 en characters long, instead 
of the default 4. 

-t o,x,d, --radix=o,x,d Print the offset within thefile before each string. The single character 

argument specifies the radix of the offset— octal, hexadecimal, or decimal. 

- -target=bf dname Specify an object code format other than your system's default format. (See 

objdump(l), for information on listing available formats.) 

-o Like-to. 


SEE ALSO 

binutiis entry in info; TheGNU Binary Utilities, Roland H. Pesch (October 1991); ar(l), nm(l), objdump(l), raniib(l). 

COPYING 

Copyright© 1993 Free Software Foundation, Inc. Permission isgranted to make and distribute verbatim copies of this 
manual provided the copyright notice and this permission notice are preserved on all copies 
Permission isgranted to copy and distribute modified versions of this manual under the conditionsfor verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to thisone. 
Permission isgranted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in theoriginal English. 


Cygn us Support, 25 Junel993 
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strip 

strip- Discard symbols from object files 

SYNOPSIS 

strip [ -Fbfdname | - - target=bfdname ] [ - Ibf d n a me | 

■ -input-target=bfd n a me ] [ -Obfdname |--output-target=bfdname ] 

[-Rsectionnameremove-seotion=s ec t i o n n a me ] [ -s] --strip-all ] 

[-SJ-g|--strip-debug ][-x|--discard-all ][-X|--discard-locals] 

[-vj--verbose ][-Vj--version ][-V[- - help ] o bj fiIe ... 

DESCRIPTION 

GNU strip discards all symbols from the object files o b j f i i e. T he list of object files may include archives. At least one 
object file must be given. 

strip modifiesthefilesnamed in its argument, rather than writing modified copies under different names 

OPTIONS 

-F bfdname, - -target=bf dna me 

-I bf dna mefdname", --input-target=bf dname 

-0 bfdname, --output-target=bf dname 
-R secti onname, - - remove-section=s ect i onname 

-s, - -strip-all 
-S, -g, - -strip-debug 
-x, --discard-all 
-X, --discard-locals 

-v, - -verbose 

-V, - -version 

SEE ALSO 

binutiis entry in info; TheGNU BinaryUtilities, Roland H. Pesch (October 1991) 

COPYING 

Copyright© 1991 Free Software Foundation, Inc. Permission isgranted to make and distribute verbatim copies of this 
manual provided the copyright notice and this permission notice are preserved on all copies 
Permission isgranted to copy and distribute modified versions of this manual under the conditionsfor verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 
Permission isgranted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in theoriginal English. 


Treattheoriginalobjfi ie asafile with the object codeformat 
b f d n a me , and rewrite it i n the same format. 

Show a summary of the optionsto strip and exit. 
Treattheoriginalobjfi ie asafile with the object codeformat 

bfdname. 

Replaceobjfi ie with afilein theoutput format bf dname. 

Remove the named section from the file This option may be given 
more than once. N otethat using thisoption inappropriately may 
make the object file unusable. 

Remove all symbols 
Remove debugging symbols only. 

Remove nonglobal symbols 

Remove compiler-generated local symbols. (These usually start with l 
or a period. 

Verbose output: list all object files modified. In the case of archives 
strip -v lists all members of the archive. 

Show the version number for strip and exit. 


CygnusSupport, 5 N ovemberl991 
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subst 

subst— Substitute defi nitions into file(s) 

SYNOPSIS 

DESCRIPTION 

subst makes substitutions into files, in away that issuitablefor customizing software to local conditions. Each v i cti m file is 
altered according to the contents of the substituti ons file 

Thesubstitutions file contains one line per substitution. A line consists of two fields separated by one or more tabs The 
first field is the name of the substitution, the second is the value. N either should contain the character#, and use of text- 
editor metacharacters likes and \ is also unwise; the name in particular is best restricted to alphanumeric. A line starting with 
# is a comment and is ignored. 

In the victim files each line on which a substitution isto be made (a target line) must be preceded by a prototype line. The 
prototype line should be delimited in such away that it will betaken as a comment by whatever program processes the file 
later. The prototype line must contain a prototype of the target line bracketed by = o< and >o=; everything else on the 
prototype line isignored. subst extracts the prototype, changes all instances of substitution names bracketed by@< and >@to 
their values, and then replaces the target line with the result. 

Substitutions are done using the sed(l) editor, which must be found in either the /bin or /usr/bin directories. To specify a 
different executable, use the -e flag. 

EXAMPLE 

Ifthesubsti tuti ons fileis 
FIRST 111 
SECOND 222 

and the victim file is 

/* =()<y =@<FIRST>@+@<SECOND>@;>()= */ 


then subst -f substitutions victim Changes victim to 
x =2; 

/* =()<y =@<FIRST>@+@<SECOND>@;>()= */ 
y = 111 + 222; 


FILES 


cti mdi r /substtmp. new New version being built 
cti mdi r/substtmp.old 0 Id version during renaming 


SEE ALSO 

sed(l) 

DIAGNOSTICS 

Complainsand halts if it is unable to create its temporary files or if they already exist. 



SuperProbe 


HISTORY 

W ritten at U niversity of Toronto by H enry Spencer. 

Rich $alz added the -e flag July, 1991. 

BUGS 

When creating a file to besubsted, it's easy to forget to insert a dummy target line after a prototype line; if you forget, subst 
ends up deleting whichever linedid in fact follow the prototype line. 

Local 


sum 

sum- C hecksum and count the blocks in a file 

SYNOPSIS 

sum [-rs] [--sysv] [--help] [--version] [file...] 

DESCRIPTION 

This manual page documents the G N U version of sum. sum computesa 16-bit checksum for each named file or the standard 
input if none are given or when a file named - is given. It printsthe checksum for each file along with the number of blocks 
in thefile (rounded up). By default, each corresponding filename is also printed if at least two arguments are specified. With 
the - -sysv option, corresponding filenames are printed when there is at least one file argument. By default, theGNu sum 
computes checksums using an algorithm that is compatible with the BSD sum and prints file sizes in units of IK blocks 

OPTIONS 

-r U se the default (BSD-compatible) algorithm. This option isinduded for compatibility with the System V 

sum. Unless the -s option was also given, it has no effect. 

-s, --sysv ComputechecksumsusinganalgorithmthatiscompatiblewiththeonetheSystemV sum uses by default 
and print file sizes in units of 512-byte blocks instead of IK. 

- - help Print a usage message and exit with a non-zero status 

- -version Print version information on standard output, then exit. 

GNU Text Utilities 


SuperProbe 

SuperProbe- Probe for and identify installed video hardware 

SYNOPSIS 

SuperProbe [-verbose] [-nol6] [-excl list] [-mask10] [-order list] [-noprobe I i st ] [-bios base] 

[-no bios] [-no dac] [-no mem] [-info] 

DESCRIPTION 

SuperProbe isa program that will attempt to determine the type of video hardware installed in an EISA/1SA/V LB-bus 
system by checking for known registers in various combinations at various locations (M icroChannel and PCI machines may 
not be fully supported; many work with the use of the -no_bios option.) This is an error-prone process, especially on UN IX 
(which usually has a lot more esoteric hardware installed than M S-D OS systems do), so SuperProbe may likely need help 
from the user. 
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superProbe runson SVR3, SVR4, Linux, 386BSD/FreeBSD/N dtBSD, M inix-386, and M ach. It should be trivial to extend 
it to work on any other UN IX-I ike operating system, and even non-UN IX operating systems. All of the operating system 
(0 S) dependencies are isolated to a singlefilefor each 0 S. 

At this time, SuperProbe can identify M DA, Hercules, CGA, M CGA, EGA, VGA, and an entire horde of SVGA chipsets. 
(Seethe - info option under "Options") It can also identify several H iColor/T rue-color RAM D AC sin use on SVGA 
boards, and the amount of video memory installed (for many chipsets). It can identify 8514/A and some derivatives but not 
XGA, or PGC (although the author intends to add those capabilities). Nor can it identify other esoteric video hardware (like 
Targa, TIGA, or M icrofield boards). 


OPTIONS 

-verbose 


-excl\l i st 


■maskio 




superProbe will be verbose and provide lots of information as it does its work. 

SuperProbe will not attempt to use any ports that require 16-bit I/O address decoding. The original ISA 
busonly specified that I/O ports be decoded to 10 bits Therefore someold cards (including many 8-bit 
cards) will misdecode references to ports that use the upper 6 bits and may get into funny states because 
they think that they are being addressed when they are not. It is recommended that this option be used 
initially if any 8-bit cards are present in the system. 

superProbe will not attempt to access any I/O ports on the specified exclusion list. Some video cards use 
rather nonstandard I/O ports that may conflict with other cards installed in your system. By specifying to 
superProbe, a list of ports already in use it will know that there cannot beany video cards that use those 
ports, and hence will not probe them (which could otherwise confuse your hardware). The exclusion list is 
specified as a comma-separated list of I/O ports or port ranges A range is specified asi ow-hi gh, and is 
inclusive. The ports can be specified in decimal, in octal (numbers begin with 0), or hexadecimal (numbers 
begin with 0x). 

Thisoption is used in combination with -exci. It tells superProbe that when comparing an I/O port 
under test against the exclusion list, the port address should be masked to 10 bits. This is important with 
older 8-bit cards that only do 10-bit decoding, and for some cheap 16-bit cards as well. Thisoption is 
simply a less drastic form of the -noi 6 option. 

Thisoption specifies which chipsets superProbe should test, and in which order. The list parameter is a 
comma-separated list of chipsdt names This list overrides the built-in default testing order. T 0 find the list 
of acceptable names use the - info option described later in this list. Note that items displayed as 
"Standard video hardware" are not usable with the -orderoption. 

Thisoption specifies which chipsets SuperProbe should not test. The order of testing will either be the 
default order, or that specified with the -order option. The list parameter is a comma-separated list of 
chipset names. To find the list of acceptable names use the - info option. Note that items displayed as 
"Standard video hardware" are not usable with the - noprobe option. 

Thisoption specifies the base address for the graphics-hardware BIOS. By default, superProbe will 
attempt to locate the BIOS base on its own (the normal address is 0x00000). If it fails to correctly locate 
the BIOS (an error message will be printed if this occurs), the -bios option can be used to specify the 
base 


-no_bios Disallow reading of the video BIO Sand assume that an EGA or later (VGA, SVGA) board is present as 
the primary video hardware. 

-no_dac Skip probingforthe RAM DAC type when an (S)VGA is identified. 

-nojnem Skip probing for the amount of installed video memory. 

-info SuperProbe will print out a listing of all the video hardware that it knows how to identify. 


EXAMPLES 

T0 run superProbe in its most basic and automated form, simply enter the following: 
SuperProbe 



tac 




NOTE 


You may want to redirect stdout to a file when you run superProbe (especially if your 0 S does not support Virtual 
Terminals on the console). 

H owa/er, if you have any 8-bit cards installed, you should initially run SuperProbe as 
SuperProbe -verbose -no16 

(the -verbose option is included so you can see what superProbe isskipping). 

Finer granularity can be obtained with an exclusion list, for example, 

SuperProbe -verbose -excl 0x200,0x220-0x230,0x250 

will not test for any device that uses port 0x200, ports 0x220 through 0x230, inclusive, or port 0x250. If you have any 8-bit 
cards installed, you should add -maskio to the list of options 

To restrict the search to Western Digital, Tseng, and Cirrus chipset, run SuperProbe as follows 
SuperProbe -order WD,Tseng,Cirrus 

BUGS 

Probably a lot at this point. Please report any bugsor incorrect identifications to theauthor. 

It is possible that superProbe can lock up your machine. Besureto narrow the search by using the-noi 6, -exci,and - 
maskio options provided to keep superProbe from conflicting with other installed hardware. 

SEE ALSO 

Thevgadoc3.zip documentation package by Finn Thoegersen, available in the M 5-DOS archives of many FTP repositories 
Programmer'sGuidetotheEGA and VGA Cards, Second Edition, by Richard Ferraro. 

AUTHOR 

David E. Wexelblat (dwex@xfree86.org) with help from D avid D awes (dawes@xfree86.org) and theXFree86 development 
team. 

Verson 2.2 


tac 

tac—Concatenate and print filesin ra/erse 

SYNOPSIS 

tac [-br] [-s separator] [--before] [--regex] [--separator=separa10r ] 

[--help] [--version] [file...] 

DESCRIPTION 

This manual page documents the GN U version of tac. tac copies each given file, or the standard input if none are given or 
when a filename of - is encountered, to the standard output with the order of the records reversed. T he records are separated 
by instances of a string, or a newline if none isgiven. By default, the separator string is attached to the end of the record that 
it follows in thefile. 
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The separator is attached to the beginning of the record that it precedes in the file. 
The separator is a regular expression. 

U se s t r i n g as the record separator. 

Print a usage message and exit with a non-zero status 
Print version information on standard output, then exit. 

GNU Text Utilities 

tail 

tan- 0 utput the last part of files 

SYNOPSIS 

tail [-c [+]N[bkm]] [-n [ + ]N] [-fqv] [--bytes=[+]N[bkm]] [--lines=[+]N] 

[-■follow] [--quiet] [--silent] [--verbose] [--help] [--version] [file...] 

tail [{-,+}Nbcfklmqv] [file...] 

DESCRIPTION 

This manual page documents the G N U version of tail, tail prints the last part (10 lines by default) of each given file; it 
reads from standard input if no files are given or when afilenameof - is encountered. If more than onefile is given, it prints 
a header consisting of the file's name enclosed in ==> and <== before the output for each file 

TheGNU tail can output any amount of data, unlikethe UNIX version, which uses a fixed size buffer. It has no -r option 
(print in reverse). Reversing a file is really a different job from printing the end of a file; the BSD tail can only reverse files 
that are at most as large as its buffer, which istypically 32KB. A reliable and more versatile way to reversefilesistheGN U 
tac command. 

OPTIONS 

tail accepts two option formats: the new one in which numbers are arguments to the option letters, and the old one in 
which a + or - and optional number precede any option letters. 

If a number (n) starts with a+, tan begins printing with the Nth item from the start of each file, instead of from the end. 

-c n, --bytes n Tail by n bytes n isanon-zero integer, optionally followed by one of the following characters to 
specify a different unit, 
b 512-byte blocks 

k 1-kilobyte blocks 

m 1-megabyte blocks 

-f, - -follow Loop forever, tryingto read more characters at the end of thefile, on theassumption that thefile 

isgrowing. Ignored if reading from a pipe If more than onefile isgiven, tail printsaheader 
whenever it gdts output from a different file to indicate which file that output isfrom. 

-l, -n n, - -lines n Tail by n lines, -l is only recognized using the old option format. 

-q, -quiet, - -silent N ever print filename headers 
-v, --verbose Always print filename headers. 

- - help Print a usage message and exit with a non-zero status 

- -version Print version information on standard output then exit. 




GNU Text Utilities 
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talk 

talk—Talk to another user 

SYNOPSIS 

talk person [ttyname] 

DESCRIPTION 

talk is a visual communication program that copies lines from your terminal to that of another user. 

Thefollowing options are available: 

person If you wish to talk to someone on your own machine then person isjust the person's login name. If you 

wish to talk to a user on another host, then person is of the form user @host. 
ttyname If you wish to talk to a user who is logged in more than once, then yn a me argument may be used to 

indicate the appropriate terminal name, wheret t yname isof the form 


When first called, talk sends the message Message from TalkDaemon@his_machine... : 
talk: connection requested by your_name@your_machine 
talk: respond with: talk your_name@your_machine 

to the user you wish to talk to. At this point, the recipient of the message should reply by typing 

talk y o u r _ n a me @y o u r _ ma c h i ne 

It doesn't matter from which machinethe recipient replies, as long as his login name is the same. Once communication is 
established, the two parties may type simultaneously, with their output appearing in separate windows. Typing control- l 
■ l will cause the screen to be reprinted, while your erase, kin, and word kin characters will behave normally. To exit, 
just type your interrupt character; talk then moves the cursor to the bottom of the screen and restores the terminal to its 
previous state. 

Permission to talk may be denied or granted by useofthemesg i command. At the outsdt, talking is allowed. Certain 
commands, in particular nroff i and pr i, disallow messages in order to prevent messy output. 

FILES 

/etc/hosts To find the recipient's machine 
/var/run/utmp To find the recipient's tty 

SEE ALSO 

mail(l), mesg(l), who(l), write(l) 


BUGS 

The version of talk 1 released with BSD 4.3 uses a protocol that is incompatible with the protocol used in the version 
released with BSD 4.2. 

HISTORY 

The talk command appeared in BSD 4.2. 


BSD 4.2,22 April 1991 
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teal 

teal— Runsthegcai program with the date of tomorrow'sday 

SYNOPSIS 

teal [ - help | --version ] \ [ --shlft=[ + |-]number ][Argument... ] 

DESCRIPTION 

teal is a program that runsgcai with a date set one day ahead (equivalent to the - - shifts option). All given arguments 
are passed unmodified to thegcai program. If thegcai program diall be called with a date other than tomorrow's date, this 
desired date can beselected by using the --shift=[+1 -jnumber option, in which [+1 - ] n u mb e r isthe number of daysthe 
desired date is distant from the actual date. The - - shift option must be given before all other arguments, which are passed 
to thegcai program. An exit status of 0 means all processing issuccessfully done; any other value means an error has 
occurred. 

OPTIONS 

--help Print a usage message listing all available options, then exit successfully. 

- -version Print the version number, then exit successfully. 

--shift=[+| - ] n u mb e r Define the displacement in [+1 - ] n u mb e r days the desired date isdistant from the actual date. 

ENVIRONMENT 

gcalprog T he gcalprog environment variable containsthefilename of the executable gcai program, which 

is used by tcai to call gcai. T akes precedence over thefilenamegcai, which is burned-in during 
thecompilation step of tcai. 


COPYRIGHT 

Copyright© 1995,1996 by Thomas Esken. This software doesn't claim completeness, correctness, or usability. On principle, 

I will not be liablefor any damagesorlosses (implicit or explicit), which result from using or handling my software. If you 
use this software, you agree without any exception to this agreement, which binds you LEGALLY. 
tcai is free software and distributed under the terms of theGN U General Public License; published by the Free Software 
Foundation; version 2 or (at your option) any later version. 

Any suggestions, improvements, extensions, bug reports, donations, proposalsfor contract work, and so forth are welcome! If 
you likethistool, I'd appreciate a postcard from you! 

Enjoy it =8") 

AUTHOR 

ThomasEsken (esken@uni-muenster.de) 
m FI agenfeld 84 
D-48147 M uenster; Germany 
Phone:+49 251 232585 


SEE ALSO 

gcal(l) 


16 July 1996 



telnet 

telnet— U ser interface to theT el net protocol 

SYNOPSIS 

telnet [-d] [-a] [-n tracefile] [-e escapechar] [[-1 user] host [port]] 


DESCRIPTION 

The telnet command is used to communicate with another host using theTelnet protocol. If telnet isinvoked without the 
host argument, it enters command mode, indicated by its prompt teinet>. In this mode, it accepts and executes the 
commands listed below. If it isinvoked with arguments, it performs an open command with those arguments 


OPTIONS 


-n tracefile 


sets the initial value of the debug toggle to True. 

Attempt automatic login. Currently, this sends theusername via the user variableof the environ 
option if supported by the remote system. The name used is that of the current user as returned 
by getiogin 2 if it agrees with the current user ID; otherwise it is the name associated with the 
user ID. 

Opens tracefile for recording trace information. See the set tracefile command in the 
"Commands" section. 

W hen connecting to the remote system, if the remote system understands the environ option, then 
user will be sent to the remote system as the value for the variable user. This option implies the -a 
option. This option may also be used with the open command. 

Sdts the initial telnet escape character to escapechar. If escape char is omitted, then there will 
be no escape character. 

Indicates the official name, an alias, or the Internet address of a remote host. 

Indicatesa port number (address of an application). If a number is not specified, the default telnet 
port is used. 


Once a connection has been opened, telnet will attempt to enable the telnetlinemode option. If thisfails, then telnet will 
revert to one of two input modes- either character-at-a-time or old line-by-line depending on what the remote system 
supports. 

When linemode isenabled, character processing is done on the local system, under the control of the remote system. When 
input editing or character echoing is to be disabled, the remote system wi II relay that information. T he remote system will 
also relay changes to any special characters that happen on the remote system, so that they can take effect on the local system. 
In character-at-a-time mode, most text typed is immediately sent to the remote host for processing. 

In old line-by-line mode, all text is echoed locally, and (normally) only completed lines are sent to the remote host. The local 
echo character (initially ”e) may be used to turn off and on the local echo. (This would mostly be used to enter passwords 
without the password being echoed.) 

If the linemode option isenabled, or if theiocaichars toggle is True (the default for old line-by-line), the user’s quit, intr, 
and flush characters are trapped locally, and sent asT elnet protocol sequences to the remote side. If linemode has ever been 
enabled, then the user's susp and eof are also sent asTelnet protocol sequences, and quit is sent as a telnet abort instead 
of break T here are options (see toggle autof lush and toggle autosynch in the following list) that cause this action to 
flush subsequent output terminal (until the remote host acknowledges the telnet sequence) and flush previous terminal 
input (in thecase of quit and intr). 
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W hile connected to a remote host, telnet command mode may be entered by typing the telnet escape character (initially 
']). W hen in command mode, the normal terminal editing conventions are available 


The following telnet commands are available. 0 nly enough of each command to uniquely identify it need be typed. (This 
is also true for arguments to the mode, set, toggle, unset, sic, environ, and display commands.) 
close Close a telnet session and return to command mode, 

display argument... D isplays all, or some, of the set and toggle values. 

mode type type isoneof several options, depending on thestateof the telnet session. Theremote host is 

asked for permission to go into the requested mode. If the remote host is capable of entering that 
mode the requested mode will be entered. Thet ype options are 


D isable the telnet linemo 
understand the linemode o| 
Enable the telnet linemoi 
understand the linemode o| 
mode 


e option, or, if the remote side does not 
ion, then enter character at a time mode 
: option, or, if the remote side does not 
ion, then attempt to enter old-line-by-line 


isig -isig Attemptto enable (disable) theTRAPsiG mode of the linemode option. This 

requires that the linemode option be enabled. 

edit -edit Attempt to enable (disable) the edit mode of the linemode option. T his 

requires that the linemode option be enabled. 

sot ttabs Attempt to enable (disable) the soft_tab mode of the linemode option. This 

requires that-softtabs the linemode option be enabled, 
litecho -litecho Attempt to enable (disable) the lit_echo mode of the linemode option. This 
requires that the linemode option be enabled. 

? Printsout help information for the mode command. 

Open a connection to the named host. If no port number is specified, telnet will attemptto [-1 
contact a Telnet server at the default port. T he host specification may be either a hostname (see 
hosts (5)for more information) or an Internet address specified in thedot notation (see ±net(3) for 
more information). The -1 option maybe used to specify the username to be passed to theremote 
system via the environ option. W hen connecting to a nonstandard port, telnet omits any 
automatic initiation of telnet options When the port number is preceded by a minus sign, the 
initial option negotiation isdone After establishing a connection, thefile in the user's home 
directory is opened. Lines beginning with a# are comment lines Blank lines are ignored. Lines that 
begin without whitespace are thestart of a machineentry. Thefirst thing on thelineisthe name of 
the machine that is being connected to. The rest of the line, and successive lines that begin with 
whitespace, are assumed to beteinet commands and are processed as if they had been typed in 
manually to the telnet command prompt. 

Close any open telnet session and exit telnet. An end-of-file (in command mode) will also close a 
session and exit. 

Sends one or more sped al character sequences to the remote host. T he followi ng are the arguments 
that may be specified (more than one argument may be specified at atime): 
abort Sends the telnet abort (Abort Processes) sequence, 

ao Sends the telnet ao (Abort Output) sequence, which should cause the 

remote system to flush all output from the remote system to the user's 
terminal. 

ayt Sends the telnet ayt (AreYou There) sequence to which theremote 

system may or may not choose to respond. 

brk Sends the telnet brk (Break) sequence, which may have significance to the 

remote system. 
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ec Sends the telnet ec (Erase Character) sequence, which should causethe 

remote system to erase the last character entered. 

ei Sends the telnet el (Erase Line) sequence, which should cause the remote 

system to erase the line currently being entered, 
eof Sends the telnet eof (End-of-File) sequence 

eor Sends the telnet eor (End of Record) sequence, 

escape Sends the current telnet escape character (initially *). 

ga Sends the telnet ga (Go Ahead) sequence, which likely has no significance 

to the remote system. 

getstatus If the remote side supports the telnet status command, getstatus will 

send the subnegotiation to request that the server send its current option 
status 


ip Sends the telnet ip (Interrupt Process) sequence, which should causethe 

remote system to abort the currently running process, 
nop Sends the telnet nop (no operation) sequence, 

susp Sends the telnet susp (suspend process) sequence 

synch Sendsthe telnet synch sequence. Thissequencecausestheremotesystem 

to discard all previously typed (but not yet read) input. This sequence is sent 
as top urgent data (and may not work if the remote system is a BSD 4.2 
system- if it doesn't work, a lowercase r may be echoed on the terminal). 

? Printsout help information forthesend command, 

rgument value, T he set command will set any one of a number of telnet variables to a specific value or to True, 
argument value The special value of f turns off the function associated with the variable; this is equivalent to using 
the unset command. The unset command will disable or set to False any of the specified 
functions The values of variables may be interrogated with thedispiay command. The variables 
that may beset or unset, but not toggled, are listed here. In addition, any of the variables for the 
toggle command may be explicitly set or unset using the si and unset commands, 
echo This is the value (initially ~e) which, when in line-by-line mode toggles 

between doinglocal echoing of entered characters (for normal processing), 
and suppressing echoing of entered characters (for entering, say, a password), 
eof If telnet isoperating in linemode or old lineby-line mode, entering this 

character as the first character on aline will cause this character to be sent to 
the remote system. Theinitial value of the eof character istaken to be the 
terminal’s eof character. 


If telnet is in localchars mode (see toggle localchars, following), and if 
telnet isoperating in character at a time mode then when this character is 
typed, a telnet ec sequence (see send ec, earlier in this man page) is sent to 
the remote system. Theinitial value for the erase character istaken to be the 
terminal's erase character. 


escape This is the telnet escape character (initially * [) which causes entry into 

telnet command mode (when connected to a remote system), 
f lushoutput If telnet is in localchars mode (see toggle localchars) and the 

fiushoutput character is typed, a telnet ao sequence is sent to the remote 
host. Theinitial value for the flush character istaken to be the terminal's 
flush character. 


interrupt If telnet is in localchars mode (see toggle localchars) and the interrupt 

character is typed, a telnet iup sequence is sent to the remote host. The 
initial value for the interrupt character istaken to be the terminal's intr 
character. 
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kill If telnet is in localchars mode (see toggle localchars), and if telnet is 

operating in character at a time mode, then when thischaracter istyped, a 
telnet el sequence is sent to the remote system. T he initial valuefor the 
kin character istaken to be the terminal's kin character, 
inext If telnet isoperating in linemode or old line-by-line mode, then this 

character istaken to be the terminal's inext character. The initial valuefor 
the inext character istaken to be the terminal's inext character, 
quit If telnet is in localchars mode (see toggle localchars) and the quit 

character istyped, a telnet brk sequence is sent to the remote host. The 
initial value for the quit character istaken to be the terminal's quit 
character. 

reprint If telnet isoperating in linemode or old line-by-line mode, then this 

character istaken to be the terminal's reprint character. The initial valuefor 
the reprint character istaken to be the terminal's reprint character, 
start If the telnettoggle-flow-control option hasbeen enabled, then this 

character istaken to be the terminal's start character. The initial valuefor 
the start character istaken to be the terminal's start character, 
stop If the telnettoggle-flow-control option hasbeen enabled, then this 

character istaken to betheterminal's stop character. The initial value for the 
km character istaken to betheterminal'sstop character, 
susp If telnet is in localchars mode or linemode is enabled, and the suspend 

character is typed, a telnet susp sequence is sent to the remote host. T he 
initial valuefor the suspend character istaken to betheterminal'ssuspend 
character. 

tracefiie This is the file to which the output, caused by netdata or option tracing 

being True, will be written. Ifitissetto -, then tracing information will be 
written to standard output (the default). 

worderase If telnet isoperating in linemode or old line-by-line mode, then this 

character istaken to betheterminal'sworderase character. The initial value 
fortheworderase character istaken to betheterminal'sworderase 
character. 

? Displaystheset unset commands 

sic state The sic command (Set Local Characters) is used to set or change the state of the special characters 

when the telnetlinemode option hasbeen enabled. Special characters are characters that get 
mapped to telnet command sequences (like ip or quit) or line-editing characters (like erase and 
kin). By default, the local special characters are exported. The variables are 
export Switch to the local defaults for the special characters. T he local default 

characters are those of the local terminal at the time telnet was started, 
import Switch to the remote defaults for the special characters T he remote default 

characters are those of the remote system at the time when the telnet 
connection was established. 

check Verify the current settings for the current special characters. Theremoteside 

is requested to send all the current special character settings and if there are 
any discrepancies with the local side, the local side will switch to the remote 
value. 

? Prints out help information for the sic command. 
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environ arguments... The environ command isused to manipulate the variables that may be sent through the telnet 
environ option. The initial set of variables istaken from the users environment, with only the 
display and printer variables being exported by default. The user variable is also exported if the 
-a or -l options are used. 

Valid arguments for the environ command are 

define vari abi e value Define the variable v a r i a b i e to have a value of va i ue. Any variables 

defined by this command are automatically exported. The value may 
be enclosed in single or double quotes so that tabs and spaces may be 
included. 

undefine variable Removeva r i a bi e from the list of environment variables 

export variable M ark the variable va r i a bi e to beexported to the remoteside. 

unexport variable M ark the variable va r i abi e to not beexported unless explicitly asked 

for by the remoteside. 

list Listthecurrentsetofenvironmentvariables.Thosemarked with a* 

will be sent automatically; other variableswill only be sent if explicitly 
requested. 

? Printsout help information fortheenviron command, 

toggle arguments... Toggle (between True and False) various flags that control how telnet respondsto events These 
flags may be set explicitly to True or False using the set and unset commands listed earlier. M ore 
than one argument may be specified. The state of these flags may be interrogated with the display 
command. Valid arguments are 

autofiush If autofiush and locaichars are both True, then when the ao or 

quit characters are recognized (and transformed into telnet 
sequences see set for details), telnet refuses to display any data on 
the user's terminal until the remote system acknowledges (via a 
telnet timing mark option) that it has processed those telnet 
sequences Theinitial valueforthistoggleisTrue if the terminal user 
had not donean “stty nofish"; otherwise, False. (See stty(l) for 
more details.) 

autosynch If autosynch and locaichars are both t rue, then when either the 

intr or quit character istyped (see set for descriptions of the intr 
and quit characters), the resulting telnet sequence sent isfollowed by 
the telnet synch sequence This procedure should cause the remote 
system to begin throwing away all previously typed input until both 
of the telnet sequences have been read and acted upon. T he initial 
value of this toggle is False. 

binary Enableor disable the telnet binary option on both input and 

output. 

inbinary Enableor disable the telnet binary option on input, 

outbinary Enableor disable the telnet binary option on output, 

crif If this is True, then carriage returns will besentas<CR><LF>. Ifthisis 

False, then carriage returns will be sent as <cr><nul>. T he initial 
value for this toggle is False. 

crmod Toggle carriage return mode. W hen this mode is enabled, most 

carriage return characters received from the remote host will be 
mapped into a carriage return followed by a linefeed. This mode does 
not affect those characters typed by the user, only those received from 
the remote host. This mode is not very useful unless the remote host 
only sends carriage return, but never linefeed. T he initial value for 
thistoggle is False. 
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debug Toggles socket level debugging (useful only to the super user). The 

initial value for this toggle is False. 

localchars If this iSTrue, then the flush, interrupt, quit, erase, and kill 

characters (see set) are recognized locally, and transformed into 
(hopefully) appropriate telnet control sequences (respectively ao, ip, 
brk, ec, and ei; see send). The initial valueforthistoggleisTrue in 
old line-by-line mode and False in character at a time mode. W hen 
the linemode option is enabled, the value of localchars is ignored, 
and assumed to always bemue. If linemode has ever been enabled, 
then quit issent as abort, and eof and suspend are sent as eof and 
susp; See send. 

netdata Toggles the display of all network data (in hexadecimal format). The 

initial value for thistoggle is False. 

options Toggles the display of some internal telnet protocol processing 

(having to do with telnet options). The initial value for thistoggle is 
False. 

prettydump When the netdata toggle is enabled, if prettydump is enabled, the 

output from the netdata command will be formatted in a more user- 
readable format. Spaces are put between each character in the output, 
and the beginning of any telnet escape sequence is preceded by an * 
to aid in locating them. 

? D isplaysthe legal toggle commands 

Suspend telnet. Thiscommand only works when the user is using the csh(l). 
command Execute a single command in a subshell on the local system. If command isomitted, then an 

interactive subshell is invoked. 

status Show the current status of telnet. This includes the peer one is connected to, as well as the current 

mode 

? command Get help. With no arguments, telnet prints a help summary. If acommand is specified, telnet 

will print the help information for just that command. 

ENVIRONMENT 

telnet usesat least the home, shell, display, and term environment variables Other environment variables may be 
propagated to the other side via the telnet environ option. 

FILES 

-/ .teinetrc User customized telnet startup values 

HISTORY 

Theteinet command appeared in BSD 4.2. 

NOTES 

On some remote systems, echo has to be turned off manually when in old line-by-line mode. 

In old line-by-line mode or linemode, theterminal's eof character isonly recognized (and sent to the remote system) when it 
is the first character on a line 
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tfmtodit 

tfmtodit—Createfontfilesforusewith groff -Tdvi 

SYNOPSIS 

tfmtodit [ -sv ][-ggf file ][-kskewchar ] tfm file map file font 

DESCRIPTION 

tfmtodit creates a font file for use with groff -Tdvi. tfm_fiie isthenameof thefont metric file for thefont. map_fiie isa 
file giving the groff names for characters in thefont; this file should consist of a sequence of lines of the form: 

n Clc2 ... 

wheren isadecimal integer giving the position of thecharacter in thefont, and ci, 02,... are the groff names of the 
character. If a character has no groff names but exists in the tfm file then it will be put in the groff font file as an unnamed 
character, font isthenameof the groff font file. The groff font file is written to font. 

The -s option should be given if thefont is special (a font is special if troff should search it whenever a character is not 
found in the current font.) If thefont isspecial, it should be listed in thefonts command in the desc file; if it is not special, 
there isno need to list it becausetroff can automatically mount it when it'sfirst used. 

To do a good job of math typesetting, groff requires font metric information not present in the tfm file. The reason for this 
is that has separate math italic fonts whereas groff uses normal italic fonts for math. The additional information required by 
groff isgiven by the two argumentstothemath_fit macro in the Metafont programs for the Computer Modern fonts. In a 
text font (a font for which math_fitting is False), M etafont normally ignores these two arguments M etafontcan be made 
to put this information in thegf file by loading the following definition after cmbase when creating cm. base: 

def ignore_math_fit(expr left_adjustment,right_adjustment) = 
special "adjustment"; 
numspecial left_adjustment*16/designsize; 
numspecial right_adjustment*16/designsize; 

Thegf file created using this modified cm. base should be specified with the -g option. The -g option should not be given 
forafontforwhich math_fitting istrue. 

OPTIONS 

-v Print the version number. 

-s Thefont isspecial. The effect of this option isto add the special command to thefont file 

-kn Theskewcharofthisfont isat position n. n should bean integer; it may be given in decimal, or with a 

leading 0 in octal, or with a leading ax in hexadecimal. The effect of this option isto ignore any kerns 
whose second component isthe specified character. 

-ggf_ f i i e gf_f i i e is a gf file produced by M etafont containing special and numspecial commandsgivingadditional 

font metric information. 

FILES 

/usr/iib/groff /font/devdvi/DEsc Devicedescription file. 

/usr/iib/grof f/f ont/devdvi/F Font description file for font F. 

SEE ALSO 

groff(l), grodvi(l), groff_font(5) 


GroffVersion 1.09,14 February 1994 
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tftp 

tftp—T rivial file transfer program 

SYNOPSIS 

tftp [host] 


DESCRIPTION 

tftp is the user interface to the Internet tftp (T rivial FileT ransfer Protocol), which allows users to transfer files to and from 
a remote machine. The remote host may be specified on the command line, in which case tftp uses host as the default host 
for future transfers (See the connect command in thefollowing section.) 


COMMANDS 

Oncetftp isrunning, it issues the prompt: 

tftp> 


and recognizes thefollowing commands 


? c o mma n d■na me ... 


connect host-name port 


get filename, 

get remotename localname, 

get filel file2 ... fiIeN 


mode t r ansfer- mode 



status 


verbose 


Print help information. 

Shorthand for "modeascii" 

Shorthand for "mode binary" 

Set the host (and optionally port ) for transfers Note that the TFTP protocol, unlikethe 
FTP protocol, does not maintain connections between transfers thus the connect 
command does not actually create a connection, but merely remembers what host is to be 
used for transfers You do not have to use the connect command; the remote host can be 
specified as part of the get or put commands. 

Get a fileor set of files from the specified sources Source can be in one of two forms: a 
filename on the remote host, if the host has already been specified; or a string of the form 
hostsfilenameto specify both a host and filename at the same time If the latter form is 
used, the last hostname specified becomes the default for future transfers 
Set the mode for transfers transfer-mode may be ascii or binary. T he default is ascii. 
Put afileor set of filesto thespecified remote file or directory. The destination can be 
in one of two forms: a filename on the remote host, if the host has already been specified; 
or a string of the form hosts: filename to specify both a host and filename at the same 
time. If the latterform isused, the hostname specified becomes the default for future 
transfers. If the remote-directory form isused, the remote host is assumed to be a 
UNIX machine. 

Exit tftp .An end-of-file also exits 

Set the per-packet retransmission time-out, in seconds 

Show current status. 

Set the total transmission time-out, in seconds. 

Toggle packet tracing. 

Toggle verbose mode 


BUGS 

Because there is no user-login or validation within theTFTP protocol, the remote site will probably have some sort of file 
access restrictions in place The exact methods are specific to each site and therefore difficult to document here. 
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HISTORY 

Thetftp command appeared in BSD 4.3. 
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tgatoppm 

tgatoppm- Convert T rudVision T arga file into a portable pixmap 

SYNOPSIS 

tgatoppm [-debug][t gaf iI e ] 

DESCRIPTION 

Reads a T ru^/ ision Targa file as input. Produces a portable pixmap as output. 

OPTIONS 

-debug Causes the header information to be dumped to stderr 
All flags can be abbreviated to their shortest unique prefix. 

BUGS 

Should really be in pnm, not ppm. 

SEE ALSO 

ppmtotga(l), ppm( 5 ) 

AUTHOR 

Partially based on tga2rast, version 1.0, by I an J. M acPhedran 
Copyright© 1989 byjef Poskanzer. 

26 August 1989 
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tifftopnm— ConvertaTIFF file into a portable anymap 

SYNOPSIS 

tifftopnm [-headerdump] tifffile 

DESCRIPTION 

tifftopnm reads a TIF F file as input and produces a portable anymap as output. T he type of the output file depends on the 
input file; if it’s black and white, a pbm file is written;, if it's grayscale, a pgmfile; otherwise a ppm file. The program tells you 
which type it is writing. 

OPTIONS 

-headerdump Dump TIFF file information to stderr. This information may be useful in debugging TIFF file 
conversion problems. 

All flags can be abbreviated to their shortest unique prefix. 
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SEE ALSO 

pnmtotiff(l), pnm(5) 

BUGS 

This program is not self-contained. To use it you must fetch theTIFF Software package listed in the other, systems file and 
configure pbmpius to useiibtiff. Seethepbmpius Makefile for details on this configuration. 

AUTHOR 

Derived byjef Poskanzerfrom tif2ras.c, which is copyright® 1990 by Sun M icrosystems, Inc. Author Patrick J. Naughton 
(naughton@wind. sun. com). 

13 January 1991 


tin, rtin, cdtin, tind 

tin, rtin, cdtin, tind-A N etnews reader 


SYNOPSIS 

DESCRIPTION 

tin isa full-screen easy-to-use N etnews reader. It can read news locally (/usr/spooi/news) or remotely (rtin or tin -r 
option) via an N NTP (Network News Transport Protocol) server, cdtin can read news locally and news archived on CD- 
ROM . 11 will automatically utilize nov (newsoverview)-style index files if available locally or via the nntp xover command, 
tin has five separate levels of operation: group selection level, spooidir selection level, group level, thread level and article 
level. U se the h (help) command to view a list of the commands available at a particular level. 

On startup, tin will show a list of the newsgroups found in $HOME/.newsrc. An arrow -> or highlighted bar will point to the 
first newsgroup. M ovetoagroup by using the terminal arrow keys (terminal-dependent) or j and k. Use PgUp/PgDn 
(terminal-dependent) or Ctrl-U and Ctrl-D to pageup/down. Enter a newsgroup by pressing Return. 

TheT ab key advances to the next newsgroup with unread articles and enters it. 

OPTIONS 

-c Create/update index files for every group in $HOME/.newsrc or file specified by -f option and mark all 

articles as read. 

-f f i i e Usethespecified file of subscribed to newsgroupsin place of $HOME/.newsrc. 

-h H dp listing all command-line options 

-h Brief introduction to tin that is also shown thefirst time it isstarted. 

-i di r Directory in which to store newsgroup index files. Default is$HOME/. tin/, index. 

-m d i r Mailbox directory to use. Default is $HOME/Maii. 

-m user M ail unread articlesto specified user for later reading. For more information read the "Automatic M ailing 

and Saving N ew N ews" section later in this manual page. 

-n Only load groups from the active file that are also subscribed to in the users .newsrc. This allows a 

noticeable speedup when connecting via a slow line. 

-p program Print program with options 

-q Q uick start without checking for new newsgroups. 

-p Purge group index files of articles that no longer exist. Care should betaken when using this command as 

it starts each and every article in each group that is accessed. On a low-speed connection, this can have an 
undesirable effect and it also knocks the hell out of your filesystem. 
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-r Read news remotely from the default N NTP server specified in the environment variable nntpserver or 

Contained in the file /etc/nntpserver. 

-r Read newssaved by -s option (not yet implemented). 

-s di r Save articles to directory. Default is$HOME/News. 

-s Save unread articlesfor later reading by -r option. For more information, see "Automatic M ailing and 

Saving New News" 

-u Create/update index filesfor every group in $HOME/.newsrc or file specified by -f option. This option is 

disabled if tin retrieves its index files via an N N T P server. 

-u Start tin in the background to updateindex files whilereading newsin the foreground. Thisoption is 

disabled if tin retrieves its index files via an N N T P server. 

-v Verbose mode for-c, -m, -s, -u, and -z options 

-w Quick mode to post an article and then exit. 

-z Only start tin if there is any new/unread news. If there is news, tin will position cursor at first group with 

unread news Useful for putting in login file. 

-z Check if there is any new/unread news and exit with appropriate status If -v option is specified, the 

number of unread articles in each group is printed. An exit code 0 indicates no news 1 that an error 
occurred, and 2 that new/unread news exists. Useful for writing scripts 

tin can also dynamically change its options by the m menu command. Any changes are written to $HOME/.tin/tinrc. 

The index daemon version, tind, only supports the -f, -h, -1, and -v options. 

INDEX FILES 

In order to keep track of threads, tin maintainsan index for each newsgroup. There are a number of methods in which 
index files can be created and updated. 

The simplest method isthat each user createsfupdateshisor her own index files that are stored in $home/. tin/, index. This 
has the advantage that any user can compile and install tin, but the disadvantage is that each user isgoingto be creating 
duplicate files and using precious disk space A good way to keep index files updated is by doing a tin -u that will update 
index files in the background while you are reading news in theforeground. You can also update index files via the system 
batcher cron with the-u option: 30 6 ***/usr/local/bin/tin -u. 

A slightly better method is to set tin setuid news and have all index files created and updated in the news spool directory 
(that is, /usr/spooi/news/. index). This has the advantage that there will only be one copy of the index files on each 
machine on your network, but the disadvantage is that you will have tin running setuid news. 

A better method isto install the tind index file updating daemon and have it create and update index filesfor all groups in 
your active file at regular intervals in the news spool directory (/usr/spooi/news/.index). This has the advantage that there 
will only be one copy of the index files on each machine on your network, and tin must not be setuid news, but the 
disadvantage is that you will have to have news permissions to install tind and root permissions to install an entry in the 
cron batcher system to havetind regularly update index files. 

The best method isto install the tind index file updating daemon on your N NTP server and have it create and updateindex 
filesfor all groups in your active file at regular intervals in thenews spool directory (/usr/spooi/news/.index).Thishasthe 
advantage that there will only be one copy of the i ndex fi les on the N N T P server for the whole of your network, but the 
disadvantage isthat you will have to install my N NTP server patches to allow tin to retrieve index file from your N NTP 
server and you must install an entry in the cron batcher system to have tind regularly update index files. (This is the method 
we use on our network of 40 to 50 machines and we have not had any problems.) 

Entering a group thefirsttimetendsto be slow because the index file must be built from scratch unless the tind update 
daemon is being used. T 0 alleviate the slowness, start tin to create all index filesfor the groups you subscribe to with 
tin -u -v and go for a coffee. Subsequent readings of a group will cause incremental updating of the index file. 
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If reading news remotely and locally updating index files operation will be somewhat slower because the articles must be 
retrieved from the N N T P server. 

NEWSADMINIST RATION 

M aintaining Netnews on large networks of machines can bea pretty time-consuming job, asl discovered when I was given 
thejob of maintaining our news system and news users. 

tin is a N ews User Agent and so most of the users were always asking questions or doing things that could be frowned upon 
by their departments. To relieve news administrators (and especially me) of this, features have been added to make life easier 
for them. 

When a user starts tin, it is possible to inform them of any important changes or information concerning the news system by 
displaying a message of the day (tnotd) file. The motd file should be created in your news lib directory (/usr/iib/news/motd) 
and should have file permissionssdt to 0644. The motd file will only bedisplayed if its contents is newer than the last time 
the user started tin. If reading news via N N TP, my xmotd patch will have to have been applied to your N NTP server. 

A user starting tin for the first time can be automatically subscribed to a list of newsgroups that are deemed appropriate by 
the news administrator. At our site the su bscri pti o n s f i le has 125 groups (our active file contains more than 400 groups with 
many only being marginally interesting to most people). The subscriptionsfile should be created in your news lib directory 
(/usr/iib/news/subscriptions) and should have file permissions si to 0644. If reading news via N NTP, my list 
subscriptions patch will have to have been applied to your N NTP server. 

If my N NTP xuser patch has been applied to your N NTP server, you will be able to log the username and machine to your 
N NTP logfilefor usage statistics 

SCREEN FORMAT 

tin has five separate levels of operation: group selection level, spooidir selection level, group level, thread level, and article 
level. 

At the group selection level, the title displays the number of subscribed groups. The newsgroups are displayed on the left of 
the screen with the number of unread articles displayed on the same line in the middle of the screen, like this: 

Selection Num><Newsgroup><Num of unread articles> 

1 alt.sou roes 10 

2 comp.sources.misc 3 

3 news.software.readers 12 

At the group level, the title containsthe name of the group, the number of conversation threads, and total number of articles, 
for example, ait. sources (7 23). If thegroup has been setup not to thread articles (for example, ait. sources is in 
$(home)/. tin/unthread), the title will be ait. sources (u 23). There are two possible display formats: 

Selection NumxUnread><Responses><Subject><Author> 

1 + 3 Bnews sources? Iain@anl433.uucp 

2 1 This question has ether@net 

or 

Selection Num><Unread><Responses><Subject (longer)> 

1 + 3 Bnews sources? 

2 1 This question has a longer subject line 

At the article level, the page header hasthefollowing format: 

<Date posted><Newsgroup> 

<Thread 1 of n> 

<Article NumxSubjectxNum of responses in thread> 
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<Author><Organization> 



COMMON MOVING KEYS 

The following table shows the common keys/commands for moving at all five levels within tin: 

Beginning of list/article Home i ("r or gat article level) 

End of list/article End $ (also g at article level) 

Pageup PgUp ~uor ~Bor b 

Pagedown PgDn "Dor ~For<sPACE> 

Lineup up arrow k (not at article level) 

Linedown Down arrow j (not at article level) 

COMMON EDITING COMMANDS 

An emacs-style editing package allows the easy editing of input strings A history list allows the easy reuse of previously 
entered strings Thefollowing commands are availablewhen editing a string: 

'A, *E Moveto beginning or end of line, respectively. 

*f, "b N ondestructive moveforward or back one location, respectively. 

-d D elete the character currently under the cursor, or send eof if no characters are in the buffer. 

*h, <del> D elete character left of the cursor. 

*k Deletefromcursortoendofline 

-p, -n M ovethrough history, previous and next, respectively. 

a l, "R Redraw thecurrent line 

<cr> Places line on history list if nonblank, appends newline, and returnsto the caller. 

<esc> Abortsthe present editing operation. 

NEWSGROUP SELECTION COMMANDS 

4 Select group 4. 

"K D elete current group from $HOME/.newsrc file. 

*l Redraw page 

~R Reset $HOME/.newsrc file. 

<cr> Read current group. 

<tab> View next group with unread news. W ill wrap around to the beginning of the group selection list looking 

for unread groups. 

b M ail a bug report or comment to the author. This isthe best way to get bugs fixed and features added/ 

changed. 

c M ark current group as all read with confirmation and go to next group in group selection list, 

c M ark current group as all read and go to next unread group in group selection list, 

d Toggle display to show just the group name or the group name and the group's description, 

g Choose a new group by name. T he position of the group within the group list will also be asked for. When 

i is entered, the new group will be the first group in the displayed list; when 8 is entered, the group will be 
the eighth group in the list; and so on. When $ isentered, the group will be the last group displayed. 




520 


M 


Parti: User Commands 


H dp screen of newsgroup sdection commands 
T ogglethedisplay of help mini-menu at the bottom of the screen. 

Toggle inverse video. 

List and allow sdection of the available spool directories Thisfeature requires a special library to be linked 
with tin to create cdtin, which can then read news from an active news feed and also from multiple CD- 
ROMs. 

M ove the current group within the group sdection list. W hen i isentered, thegroup will become the first 
displayed group in the list; when 8 isentered, thedghth group in the list; and soon. When $ isentered, 
thegroup will be the last group displayed. 

User-configurable Options menu (for more information, see the "Global Options M enu" section later in 
thismanual page). 

Quit tin. 

Quit tin. 

Toggle display of all subscribed-to groups and just the subscribed-to groups containing unread articles. 

C ommand has no effect if groups were read from the command line when tin was started. 

Subscribe to current group. 

Subscribe to groups matching user-specified pattern. 

U nsubscribeto current group. 

U nsubscribeto groups matching user-specified pattern. 

Print tin version information. 

Post an article to current group. 

List articles posted by user. T he date posted, the newsgroup, and the subject are listed. 
Thefirsttimethiscommand is called, it will yank in all groups from $LiB-DiR/activethatarenotin 

$HOME/. newsrc. 

After any groups have been subscribed/unsubscribed to, this command, if pressed again, will reread $home/ 

.newsrc and display only the subscribed groups 

Reread the active file to see if any new news has arrived since starting tin. 

M ark all articles in the current group as unread. 

U ndeldte previously deleted group by "k command from $home/. newsrc. 

Group forward search. 

Group backward search. 


SPOOL DIRECTORY SELECTION COMMANDS 

4 Select spool directory 4. 

-l Redraw page 

<cr> Read newsfrom selected spool directory. 

b M ai I a bug report or comment to the author. T his is the best way to gdt bugs fixed and features 

added/changed. 

h H eip screen of spool directory selection commands 

h Toggle the display of help mini-menu at the bottom of the screen, 

i Toggle inverse video, 

q Return to previous level, 

o Quit tin. 

v Print tin version information. 
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GROUPINDEX COMMANDS 

4 Select article 4. 

“K Kill current article (for more information, see the "Automatic Kill and Selection" section later in this 

manual page). 

~l Redraw page 

<cr> Read current article. 

<tab> V iew next unread article or group, 

a Authorforward search. 

a Author backward search, 

c M ark all articles as read with confirmation, 

c M ark all articles as read and go to next group with unread news 

d Toggle display to show just the subject or the subject and author, 

g C hoose a new group by name, 

h Help screen of group index commands. 

h Toggle the display of help mini-menu at the bottom of the screen, 

i Toggle inverse video. 

k M ark articl^thread as read and advance to next unread article/thread. 

i List the author of each response in current thread and enter thread selection level, 

m M ail current artidefthread/auto-selected (hot) artidesfartides matching pattern/tagged articles to someone. 

m User-configurable Options menu (for more information see "Global Options M enu" section), 

n Goto next group. 

n G o to next unread article. 

o 0 utput current articlefthread/autoselected (hot) articledarticles matching pattern/tagged articles to 

printer. 

p Go to previous group, 

p Go to previous unread article 

q Return to previous level. 

q Quit tin. 

s Savecurrent article/thread/autosel ected (hot) articled articles matching pattern/tagged articles to fileffilesf 

mailbox. T o save to a mailbox, enter = or =maiibox when asked for filename to save to. T o savein 
<newsgroup name>/<f iiename> format, enter +fiiename. Environment variables are allowed within a 
filename (for example $souRCES/dir/tnename). 

t Tag current arti clef thread for mailing (m)/piping (|)/printing (o)/saving (s)/crossposting (x). 

u Toggle display to show all articles as unthreaded or threaded, 

u U ntag all articles that were tagged, 

v Print tin version information, 

w Post an article to current group. 

w List articles posted by user. T he date posted, the newsgroup, and the subject are listed, 

x C rosspost already posted current artide/thread/autoselected (hot) artidesfartides matching pattern/tagged 

articles to another newsgroup(s). Useful for reposting from global to local newsgroups, 
x M ark all unread articles that have not been selected as read, redo screen to reflect changes, and put index at 

the first thread to begin reading. Pressingx again will toggle back to the way it was before See - command 
for clearing the toggle effect, 
z M ark current article as unread, 

z Mark current thread as unread. 
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/ Search forward for specified subject. 

? Search backward for specified subject. 

Show last message. 

I Pipe current article/thread/autoselected (hot) articledarticles matching pattern/tagged articles into 

command. 

* Select current thread for later processing. 

* Toggle selection of current thread. If at least one unread art in thread (but not all unread arts) is selected, 
then all unread arts become selected. 

@ Reverseall selectionson all articles 

Undo all selectionson all articles 11 clears the toggle effect of x command. Thus after first doing an x, you 
can then do ' to reset articles Thus, you can iteratively whittle down uninteresting threads 
+ Perform autoselection on current group. 

; For each thread in current group, if it at least one unread art is selected, all unread arts become selected. 

This is useful for autoselection on author when the reader wants to see the entire thread. 

= Prompts for a pattern with which to match on. All threads whose subjects match the pattern will be 

selected. A pattern of * will match all subjects Entering just <cr> will cause the previous pattern to be 
used. 

THREAD LISTING COMMANDS 

4 Select article 4 within thread. 

-l Redraw page 

<cr> Read current article within thread. 

<tab> View next unread article within thread. 

b M ail a bug report or comment to theauthor. T his isthe best way of getting bugsfixed and features added/ 

changed. 

c M ark thread as read after confirmation and return to previous level, 

d Toggle display to show just the subject or the subject and author, 

h H elp screen of thread listing commands 

h Toggle the display of help mini-menu at the bottom of the screen, 

i Toggle inverse video. 

k M ark thread as read and return to previous level. 

q Return to previous level. 

q Quit tin. 

r Toggle display to show all articles or only unread articles. 

b M ail a bug report or comment to theauthor. This isthe best way of getting bugsfixed and features added/ 

changed. 

t Tag current articlefor mailing (m)/piping (|)/printing (o)/saving (s)/crossposting (x). 

t Return to group index level, 

v Print tin version information, 

z M ark current article in thread as unread, 

z M ark all articles in thread as unread. 

ARTICLE VIEWER COMMANDS 

0 Read the base article in this thread. 

4 Read response4 in thisthread. 

■h Show all of the article's mail header. 
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Kill current article (for more information, see the "Automatic Kill and Selection" section) 

Redraw page 

Go to next base article 

Go to next unread article. 

Authorforward search. 

Author backward search. 

M ark all articles as read with confirmation and return to group selection level. 

M ark current group as all read and go to next unread group in group selection list. 

Toggle rot-13 decoding for this article 

D elete current article. It must have been posted by the same user. T hecancel message can be seen in the 
newsgroup control. 

Post a follow-up to the current article with a copy of the article included. 

Post a follow-up to the current article. 

H elp screen of article page commands 

Toggle the display of help mini-menu at the bottom of the screen. 

Toggle inverse video. 

M ark article as read and advance to next unread article 
M ark thread as read and advance to next unread thread. 

M ail current articlefthread/autoselected (hot) articles/articles matching pattern/tagged articles to someone 
User-configurable Options menu (for more information, see the "Global Options M enu" section later in 
thismanual page). 

Go to the next article. 

Go to the next unread article 

0 utput current articl^thread/autoselected (hot) articled articles matching pattern/tagged articles to 
printer. 

0 utput article/thread/tagged articles to printer. 

Go to the previous article 
Go to the previous unread article 
Return to previous level. 

Quit tin. 

Reply through mail to the author of the current article with a copy of the article included. 

Reply through mail to the author of the current article 

Save current article/thread/autoselected (hot) articled articles matching pattern/tagged articles to fileffilesf 
mailbox. T o save to a mailbox enter = or =maiibox when asked for filename to save to. T o save in 
<newsgroup name>/<f iiename> format, enter +fiiename. Environment variables are allowed within a 
filename (such aS$SOURCES/dir/filename). 

Return to group selection level. 

T ag current articlefor mailing (m)/piping (| )/printing (o)/saving (s)/crossposting (x). 

Print tin version information. 

Post an article to current group. 

List articles posted by user. The date posted, the newsgroup and the subject are listed. 

C rosspost already posted current article/thread/autoselected (hot) article^artides matching pattern/tagged 
articles to another newsgroup(s). Useful for reposting from global to local newsgroups. 

Mark article as unread. 

Article forward search. 

Article backward search 
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! Pipe current article/thread/autoselected (hot) artide^artides matching pattern/tagged articles into 

command. 

< Go to thefirst article in the current thread. 

> Go to the last article in the current thread. 

* Select current thread for later processing. 

* Toggle selection of current article. 

@ Reverse article selections. 

U ndo all selections on current thread. 


GLOBALOPTIONSMENU 


This menu is accessed by pressing m at all levels. I tallows the user to customize the behavior of tin. Theoptions are saved to 
thefile$HOME/.tin/tinrc. Use<sPACE> to toggle the required option and <CR>to set. 


Auto save 

Editor offset 

M ark saved read 
Confirm Command 

D raw arrow 
Print header 

Goto 1st unread 

Scroll full page 
Catch upon quit 

Thread articles 

Show only unread 
Show description 

Show Author 

Process type 


Automatically save articles/threads by "Archive-name:" line in article header and post process them 
if processtypeisnotsetto None. 

Set on if the editor used for posting, follow-ups and bug reports has the capability of starting and 

positioning the cursor at a specified line within afile 

Allows saved artide^threadsto be automatically marked as read. 

Allows certain commands (such asc catchup) that require user confirmation to be executed 
immediately if set off. 

Allows groups/articles to be selected by an arrow -> if set on or by a highlighted bar if set off. 

This allows the complete mail header or only the "Subject:" and "From:" fields to be output when 
printing articles. 

This allows the cursor to be placed at the first/last unread article upon entering a newsgroup with 
unread news 

If set on, scrolling of groupsfarticles will be a full page at a time; otherwise half a page at a time 
If set on, the user is asked when quitting if all groups read during the current session should be 
marked read. 

If set on, articles will be threaded in all groups (default); otherwise, articles will be shown 
unthreaded. T hreading or unthreading is possible on a per-group basis by sdtti ng the group 
attribute variable thread_arts to ON/OFF in the file $H0ME/. tin/attributes. 

If set on, show only new/unread articles otherwise, show all articles. 

If set on, show a short descriptive text for each displayed newsgroup. The text used is taken from 
the $LIBDIR/newsgroups file. 

If set None, only the "Subject:" line will be displayed. If set Addr, "Subject:" line and the address 
part of the "From:" line are displayed. If set Name, "Subject:" line and the author'sfull name part of 
the "From:" line are displayed. If set Both, "Subject:" line and all of the"From:" lineare displayed. 
This specifies the default type of post processing to perform on saved articles. Thefollowing types 
of processing are allowed: 

■ None 

■ U npacking of multipart shell archives 

■ U npacking of multipart uuencoded files 

■ U npacking of multipart uuencoded files, which produce a *. zoo archive whose contents are 
listed 

■ U npacking of multipart uuencoded files, which produce a *. zoo archive whose contents are 
extracted 

■ U npacking of multipart uuencoded files, which produce a *. zip archive whose contents are 
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Sort articles by 


Save directory 
M ail directory 


Printer 


■ U npacking of multipart uuencoded files, which produce a *. zip archive whose contents are 
extracted 

■ Unpacking of multipart uuencoded files, which produce an *.iha archive whose contents are 
listed (AmigaDOS version only) 

■ Unpacking of multipart uuencoded files, which produce an *.iha archive whose contents is 
extracted (AmigaDOS version only) 

This specifies how articles should be sorted. Thefollowingsort types are allowed: 

■ Don’t sort articles (default). 

■ Sort articles by "Subject:" field (ascending and descending). 

■ Sort articles by "From:" field (ascending and descending). 

■ Sort articles by "D ate" field (ascending and descending). 

The directory where articles/threads are to be saved. D efault is $HOME/News. 

Thedirectory where articles/threads are to be saved in mailbox format. Thisfeature is mainly for 
use with the eim mail program. It allows the user to save articles, threads, or groups simply by 
giving = as the filename to save to. 

The printer program with options that isto be used to print articles Default isiprfor BSD 
machines and ip for SydV machines. 


tinrc CONFIGURABLE VARIABLES 


Thefollowing variables are user-configurable by editing $home/. tin/tinrc directly. 11 is hoped to eventually provide a menu 
to allow the setting of the most common variables. 


beginner_level 

display_reading_prompt 

force_screen_redraw 

groupname_max_length 

default_slgflle 

editor_format 

reread_active_file_secs 

save_to_mmdf_mailbox 

show_last_line_prev_page 


If set on, articles/threads will be saved in batch mode when save-s or mail -m isspecified on 
the command line Default is off. 

If set on, a mini-menu of the most useful commands will be displayed at the bottom of the 
screen for each level. Default isoN. 

T he prompt Reading... will be displayed when reading an article from an N NTP server to 
provide fealback to the user. D efault is on. 

Specifies whether a screen redraw should always be done after certai n external commands. 
Default is off. 

M aximum length of the names of newsgroups to be displayed so that more of the 
newsgroup description can be displayed. D efault is 132. 

The path that specifies the signature file to use when posting, following up to, or replying to 
an article If the path is a directory, then the signature will be randomly generated from files 
that are in the specified directory. Default is $home/ . sig. 

T he format string used to create the editor start command with parameters. D efault is %e 
+%N %F (for example/bin/vi +7 .article). 

The character used to show that an articl^thread is autoselected (hot). Default is*. 

The character used in quoting included text to articlefollow-ups and mail replies The 1 1 
character represents a blank character and is replaced with ■ 1 when read. D efault is ■: 1 . 
The news active file is reread at regular intervals to show if any new news has arrived. 
Default is300 seconds 

The character used to show that an article will return. Default is -. 

Allows articles to be saved to an mmdf-style mailbox instead of mbox format. Default is off 
unless reading newson SCO UN IX, which uscsmmdf by default. 

The last line of the previous page will be displayed as the first line of next page. Default is 

OFF. 
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slow_speed_terminal 

tab_after_X_selection 

tab_goto_next_unread 

unread_art_mark 

use_builtin_inews 

use_keypad 


Strips the blanks from the end of each line, thereby speeding up the display when reading 
on a slow terminal or via modem. Default is off. 

If enabled, will automatically go to thefirst unread artideafter having selected all hot 
articles and threads with thex command at group index level. D efault is off. 

If enabled, pressing Tab at the article viewer level will goto the next unread article 
immediately instead of first paging through the current one Default is on. 

T he character used to show that an article has not been read. D efault is +. 

Allows the built-in NNTP inews to be enabled/disabled. Default isoN (enabled). 

Allows the scroll keys on the keypad to be enabled/disabled on supported terminals Default 

iSOFF. 


GROUP ATTRIBUTES 

tin allows certain attributes to be set on aper-group basis These group attributes are read from thefile$HOME/. tin/ 
attributes. A later version will providea menu interface to set ail the attributes. At present, you will have to edit thefile 
with your editor:-(. Thefollowing group attributes are available: 

newsgroup=alt.sources 

maildir=/usr/iain/Mail/sources 

savedir=/usr/iain/News/alt.sources 

sigfile=/usr/iain/.funny sig 

organization=Wacky Bits Inc. 

followup to=alt.sources.d 

printer=/usr/local/bin/a2ps -nn ] /bin/lpr 

auto save=0N 

batch save=0FF 

delete trip files=0N 

show only unread=OFF 

thread arts=0N 

show author=1 

sort art type=5 

post proc type=1 

N ote that the newsgroup=<groupname> line has to be specified before the attributes are specified for that group. 

All attributes are set to a reasonable default so you only have to specify the attribute that you want to change (for example, 

All toggle attributes are sdt by specifying on/off. 

The show_author attribute isspecified by a number from thefollowing range: o=none i =username, 2=network address, 
3=both. 

The sort_art_type attribute is specified by a number from thefollowing range: o=none, i=subject descending, 2=subject 
ascending, 3=from descending, 4=from ascending, s=datedescending, 6=dateascending. 

The post_proc_type attribute isspecified by a number from thefollowing range: o=none i =unshar, 2=uudecode 
3=uudecode& list zoo archive, 4=uudecode& extract zoo archive 5=uudecode & list zip archive 6=uudecode& extract zip 
archive. (If running on AmigaD 0 S, the zoo optionsare replaced by their corresponding iha archiver options.) 

AUTOMATIC KILL AND SELECTION 

W hen there is a subject or an author that you are either very interested in, or find completely uninteresting, you can easily 
instruct tin to autoselect or autokill articles with specific subjects or from specific authors. These instructions are stored in a 
kill file. 

This menu isaccessed by pressing "k at the group and page levels. It allows the user to kill or select an article that matches 
the current "Subject:" line, "From:" line or a string entered by the user. The user-entered string can be applied to the 
"Subject:" or "From:" lines of an article. T he km description can be limited to the current newsgroup or it can apply to al I 
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newsgroups. Once entered, the user can abort the command and not save the km description, edit the kin file or save the 
kin description. 

0 n starting tin, theuser's km file $home/ . tin/kin is read and on entering a newsgroup any km or select descriptions 
are applied. 

Articles that match a km description are marked killed and are not displayed. Articles that match an autoselect description 
are marked with an * when displayed. 

POSTING ARTICLES 

tin allows posting of articles, follow-up to already posted articles, and replying direct through mail to the author of an 
article 

Use the w command to post an article to a newsgroup. After entering the post subject, the default editor (such asvi) or the 
editor specified by the $visual environment variable will be started and the article can be entered. To crosspost articles, 
simply add acommaand thenameof the newsgroup(s) to the end of the "N ewsgroups;" line at the beginning of the article. 
After saving and exiting the editor, you are asked if you wish to abort posting the article, edit the article again or post the 
article to the specified newsgroup(s). 

Use the w command to display a history of the articles you have posted. The date the article was posted, which newsgroups 
the article was posted to, and the article's subject line are displayed. 

Usethef/F command to post a follow-up article to an already posted article. Thef command will copy the text of the 
original article into the editor. The editing procedure is the same as when posting an article with thewcommand. 

Usether/R command to reply direct through mail to the author of an already posted article. T her command will copy the 
text of the original article into the editor. The editing procedure is the same as when posting an article with thewcommand. 
After saving and exiting the editor, you are asked if you wish to abort sending the article, edit the article again, or send the 
article to the author. 

CUSTOMIZING THE ARTICLE QUOTE STRING 

When posting a follow-up to an article or replying direct to the author of an article via e-mail, the text of the article can be 
quoted. The beginning of thequoted text can contain information about the quoted article (for example, the N ameand the 
M essagelD of the article). To allow for different situations, certain information from the article can be used in thequoted 
string. Thefollowing variables are expanded if found in thetinrc variables maii_quote_format= or news_quote_format=: 
%a Address (e-mail) 

%d D ate 

%f Full address (%n <%a>) 

%g G roupname 

%m M essage ID 

%n Name of user 

For example, 

mail_quote_format=On %D in %G you wrote: 
news_quote_format=In %M, %F wrote: 

would expand when used to: 

On 21 Jul 1992 09:45:51 -0400 in alt.sources you wrote: 

In <abcINN123@anl433.uucp>, Iain Lea (iain@erlm.siemens.de) wrote: 

MAILING, PIPING, PRINTING, REPOSTING, AND SAVING ARTICLES 

The command interface to mail (m), pipe (|), print (o), crosspost (x) and save(s) articles isthe same for ease of use 

The initial command will ask you to select which article thread, hot (autoselected) regex pattern, tagged articles you wish to 

mail, pipe, and so on. 
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T agged articles must have already been tagged with the t command. All tagged articles can be untagged by the u untag 
command. 

If regex pattern matching is selected, you are asked to enter a regular expression (for example, to match all article subject 
linescontainingnet News, you must enter *net News*).Any articlesthat match theentered expression will bemailed, 
piped, and so on. 

To save articles to a mailbox with the nameof the current newsgroup (for example, Ait. sources) enter = or =<maiibox 
name> when asked forthesavefilename. 

TO save articles in <newsgroup name>/<f ilename> format, enter +<f ilename>. 

W hen saving articles, you can specify whether the saved files should be post processed (such as unshar shell archive, 
uudecode multiple parts, and so on). A default process type can beset by the Process type: in the m Options menu. 

AUTOMATIC MAILING AND SAVING NEW NEWS 

tin allows new/unread news articles to bemailed (-m option)/saved (-s option) in batch mode for later reading— useful 
when going on holiday and you don't want to return and find that expire has removed a whole load of unread articles It's 
best to run from crontab every day while away, after which you will be mailed a report of which articles were mailed/saved 
from which newsgroups and the total number of articles mailed/saved. Articles are saved in a private news structure under 
your <savedir> directory (default is $HOME/News). 

Be careful of using this option if you read a lot of groups because you could overflow your filesystem. If you only want to 
save a few groups, it would be best to back up your full $home/. newsrc and create a new one that only contains the 
newsgroups you want to mail/save. Saved newscan be read later by tin -r. 

tin -m lain -c -f newsrc.maii M ail any unread articlesin newsgroups specified in file newsrc. mail 

tin -s -c -f newsrc.save Save any unread articles in newsgroups specified in file newsrc. save 

tin -r Read any articles saved by tin -s 

SIGNATURES 

tin will recognize a signature in either $home/. signature or $HOME/.sig. If $home/. signature exists, then the signature 
will be pulled into the editor for mail commands A signature in $home/. signature will not be pulled into the editor for 
posting commands because inews will append the s'gnature itself. 

A signature in $HOME/.sig will be pulled into theeditor for both posting and mailing commands. 

The following is an example of a $home/. sigfile: 

NAMES Iain Lea iain.lea@erlm.siemens.de 

SNAIL Bruecken Strasse 12, 8500 Nuernberg 90, Germany 

PHONE +49-911-331963 (home) +49-911-3089-407 (work) 

tin also has the capability to generate random signatures on a per-newsgroup basis if so desired. T he way to accomplish this 
is to specify the default signature or the group attribute sigfile as a directory. If, for example, the sigfile path is /usr/iain/ 
.sigs and .sigs is a directory, then tin will select a random signature from any file that is in the directory .sigs (note: one 
signature per numbered file). A random signature can also consist of a fixed part signature that can contain your name, 
address, and so on, followed by the random sig. Thefixed part of the random sig is read from thefile$HOME/.sigfixed. 

ENVIRONMENT VARIABLES 

tinrc D efinethisvariable if you want to specify command-line optionsthat tin should bestarted with to 

save typing them each timeit is started. The contents of the environment variable are added to the 
front of the command-line options before it is parsed, therefore allowing an option specified on the 
command line to override the same option specified in the environment. 
tin_homedir D efi nethis variable if you do not want the .tin directory in $HOME/.tin. For example, if you want 

all tin's private files in /tmp/.tin, you would set tindir to /tmp. 
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TIN_INDEXDIR 

TIN_LIBDIR 

TIN_SPOOLDIR 

TIN_NOVROOTDIR 

TIN_ACTIVEFILE 

NNTPSERVER 

DISTRIBUTION 

ORGANIZATION 

REPLYTO 

ADD_ADDRESS 


BUG_ADDRESS 

MAILER 

VISUAL 

AUTOSUBSCRIBE 


Define this variable if you do not want the .index directory in $home/. tin/.index. For example 
if you want all tin's index files in /tmp/. index, you would set tin_indexdir to /tmp. 

Define this variable if you want to override the libdir path that was compiled into the tin binary 
Via the Makefile. 

D efine this variable if you want to override the spooldir path that was compiled into the tin 
binary via the Makefile. 

Define this variable if you want to overridethe novrootdir path that was compiled into the tin 
binary via the Makefile. 

Define this variable if you want to override the libdir/ active path that was compiled into the tin 
binary via the Makefile. 

The default N NTP server to remotely read news from. This variable only needs to beset if the -r 
command-lineoption isspecified and the file/etc/nntpserver does not exist. 

Sdt the article header field "D istribution:" to the contents of the variable instead of the system 
default. 

Set the article header field "0 rganization:" to the contents of the variable instead of the system 
default. This variable has precedence over thefile$HOME/. tin/organization that may also contain 
an organization string. If you are reading news on an Apollo DomainOS machine the environment 
variable newsorg has to be used instead of organization. 

Set the article header field "Reply-To:" to the return address specified by the variable This is useful 
if the machine is not registered i n the UUCP mai I mapsor if you wish to receive rep lies at a 
different machine. T his variable has precedence over the file $home/. tin/ repiyto that may also 
contain a return address 

This can contain an address to append to the return address when replying directly through mail to 
somebody whose mail address is not directly recognized by the local host. For example say the 
return address is useriabigvax, but bigvax is not recognized by your host, so therefore the mail 
will not reach user. But the host uttevax is known to recognize your host and bigvax, so if 
addaddress is set (for example, setenv add_address oiittevaxforcshor 

set ADD_ADDRESS Olittevax 

and export add_address for sh), the address 

user@bigvax@littlevax will beused and the mail will reach user@bigvax. 

This variable has precedence over the file 

$HOME/.tin/add_address 

that may also contain an address. 

If the b command bug report mail address is not correct, this variable should be set to the correct 
mail address. Thisvariablehasprecedenceoverthefile 

$HOME/.tin/bug_address 

that may also contain a mail address 

This variable has precedence over the default mailer that is used in all mailing operations within 
tin (for example replying rR, and bug reports b). 

This variable has precedence over the default editor (for example, vi) that is used in all editing 
operations within tin (for example postingw, replying rR, follow-upstF, and bug reportSB). 
tin interprets thisvariable similarly to ™. It containsa list of patterns separated by commasand 
possibly prefixed with exclamation points A new group ischecked against the list of patterns; if it 
matches, tin subscribes the user to the group without further query. An exclamation point negates 
the meaning of a match on this pattern and can beused to cancel certain matches For example, 
setting autosubscribe=coihp . os. unix. *, talk. *,! talk. politics. * will automatically subscribe 
the user to all newsgroups in the comp. os. unix hierarchy, and all talk groups other than 
talk. politics groups (which will be queried for as usual). 
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autounsubscribe tin interprets this variable similarly to rn. It is handled I ike the autosubscribe variable, but 
groups matching the list are unsubscribed from without further query. For example setting 
AUTOUNsuBscRiBE=ait.flame.*,u*, !uk.* will automatically unsubscribe the user from all new 
ait. flame groups and all groups starting with u (university groups) other than uk groups (which 
will be queried for as usual). 

TIPS AND TRICKS 

tin can pretty much be navigated by using the four cursor keys The left-arrow key goes up a level, the right-arrow key goes 
down a level, the up-arrow key goes up a line (or page, at article viewer level) and the down-arrow key goes down a line (or 
page, at article viewer level). 

Thefollowing newsgroups provide useful information concerning news software: 

- - news, software, readers Information about news user agents tin, rn, nn, vn, and so on 

- - news.software.nntp Information about N NTP 

- -news.software.b Information about news transport agents Bnews, cnews, and inn) 

--news, answers Frequently asked questions (FAQ s) about many different themes 

M any prompts (for example, Mark everything as read? (y/n):) within tin offer a default choice that the cursor is 
positioned on. W hen you press <CR>, thedefault valueistaken. 

M any prompts (for example, Post subject n>) within tin can beaborted by pressing <£SC >. 

When tin is run in an xterm window, it will resize itself each time the xterm is resized, 
tin will reread the active file at set intervalsto show any newly arrived news. 

xterm BUTTONS 

If the environment variable term issdt to xterm, then button pressing can be used to select groups and articles. 

In theGroup Selection menu, if the mouse is pointing beforethe group's listing region, the previous page is selected (just 

like b). If the mouse is pointing after the group's listing region, the next page isselected (just like space). If the mouse is 

pointing at a group, then 

Left button M oves to the group pointed at 

Other buttons M oveto and select the group pointed at, just like <cr> 

In the Article menu, if the mouse is pointing beforethe article listing region, the previous page isselected (just like b). If the 
mouse is pointing after the article listing region, the next page is selected (just like space). If the mouse is pointing at an 
article then 

Left button M ovesto theartide pointed at 

Center button Reads next unread articlefrom that pointed at, just like <tab> 

Right button Readsartide pointed at, just like <cr> 

In theThread menu, if the mouse is pointing beforethe article listing region, the previous page is selected (just like b). Ifthe 
mouse is pointing after the article listing region, the next page is selected (just like space). If the mouse is pointing at an 
article then 

Left button M ovesto theartide pointed at 

Center button Reads next unread articlefrom that pointed at, just like <TAB> 

Right button Reads article pointed at, just like <C R> 

In the Spool Selection menu, if the mouse is pointing before the spool listing region, the previous page is selected (just like 
b). If the mouse is pointing after the spool listing region, the next page is selected (just like space). If the mouse is pointing 
at a spool selection, then 
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Left button M ovesto thespool pointed at 

Other buttons M oveto and select thespool pointed at, just like <cr> 

In other menus and areas, button pressing reverts back to usual cut and paste of xterm, but after one click of any button. 


FILES 

$HOME/.newsrc 
$HOME/.newsauth 
$HOME/.tin/tinrc 
$HOME/.tin/attributes 
$HOME/.tin/.index 
$HOME/.tin/.mailidx 
$HOME/.tin/.saveidx 
$HOME/.tin/active.mail 
$HOME/.tin/active.save 
$HOME/.tin/add_address 
$HOME/.tin/bug address 
$HOME/.tin/kill 
$HOME/.tin/organization 
$HOME/.tin/posted 
$HOME/.tin/replyto 
$HOME/.signature 
$HOME/.Sig 
$HOME/.sigfixed 
/usr/lib/news/motd 
/usr/lib/news/newsgroups 
/usr/lib/news/subscriptions 


Subscribed to newsgroups 

nntpserver password pairsfor N NTP servers that require authorization 
Options 

Contains user-specified group attributes 

N ewsgroups index files directory 

M ailgroups index files directory 

Saved newsgroups index filesdirectory 

Active file of users mailgroups 

Active file of users saved newsgroups 

Address to add to when replying through mail 

Address to send bug reports to 

Article kill and autoselection file 

String to replace default organization 

H istory of articles posted by user 

H ost address to use in "Reply-To:" mail header 

Signature 

Signature 

Fixed part of a randomly generated signature 

N ews message-of-the-day file 

Short description of all newsgroups 

List of newsgroups to subscribe first-time user to 


BUGS 

There are bugs somewhere among the creeping featurism. Any bugs found should be reported by theB (bug report) 
command. 

Coredumps when setting certain toggle options from the Options menu at article viewer level. 

Coredumps when killing last article in a thread at article viewer level. 

HISTORY 

Based on thetass newsreader that was developed by Rich Skrentaand posted to ait.sources in M arch 1991. tass was 
itself heavily influenced by notes, which was developed at the University of Illinois by Ray Essick and Rob Kolstad in 1982. 
vi .0 plo (full) was posted in eight parts to ait.sources on 23 Aug 1991. vi .0 pli (full) was posted in eight parts to 
ait. sources on 03 Sep 1991. vi .0 pl 2 (full) was posted in ninepartsto ait. sources on 24 Sep 1991. vi .0 pl3 (patch) 
was posted in fourpartsto ait. sources on 30 Sep 1991. vi .0 pl4 (patch) was posted in two parts to ait. sources on 02 
Oct 1991. vi .0 pl5 (patch) was posted in fourpartsto ait. sources on 17 Oct 1991. vi .0 pl6 (patch) was posted in five 
parts to ait. sources on 27 Nov 1991. vi .0 pl7 (patch) was posted in two parts to ait. sources on 27 N 0 v 1991. vi .1 
plo (full) was posted in eleven parts to ait. sources on 13 Feb 1992. vi .1 pli (full) was posted in twelve parts to 
alt. sources on 24 M ar 1992. vi .1 pl 2 (patch) was posted in fourpartsto ait. sources on 30 M ar 1992. vi .1 pl3 (full) 
was posted in fifteen parts to ait.sources on 13 M ay 1992. vi .1 pl4 (full) was posted in fifteen parts to ait.sources on 
22 J un 1992. vi .1 pls (patch) was posted in seven parts to ait. sources on 11 Aug 1992. vi .1 pl6 (full) was posted in 
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fifteen parts to ait. sources on 14 Sep 1992. vi .i pl7 (patch) wasposted in ten partsto ait. sources on 15 Nov 1992. 
vi .i pls (patch) wasposted in six partsto ait. sources on 06 Dec 1992. vi .i pl9 (patch) wasposted in three partsto 
ait.sources on 20 M ar 1993. vi .2 plo (full) wasposted in fourteen partsto ait.sources on 25 M ay 1993. vi .2 pli 
(patch) wasposted in eight partsto ait. sources on 14Jul 1993. vi .2 pl 2 (patch) wasposted in partsto ait.sources in 
September 1993. 


CREDITS 

Rich Skrenta 
Bill Davidsen 
M ike Gleason 
Arnold Robbins 
Jim Robinson 
Rich Salz 
Dave Taylor 
ChrisThewalt 
M ark Tomlinson 
Andreas W rede 
Dieter Becker 


Author of tass v3.2, which this newsreader used as its base 

Author of envarg. c environment variable reading routine 

Author of sigfiie.c random signature generation routines 

Author of strftime.c date formatting routine 

Coauthor of km. c article kill and autoselection routines 

Authorofwiidmat.c pattern matching and parsedate.y date parsing routines 

Author of curses. c from the elm mai Ireader 

Author of getiine. c emacs-style editing routine 

For porting tin to the AmigaDO S operating system 

For porting tin to the 0 S/2 operating system 

For generously posting certain releases for me when my net connection was removed by a group of 
very short-sighted people 
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AUTHOR 

lain Lea(iain.lea@erlm.siemens.de) 


Version 1.2 PL2 


tload 

tioad—Graphic representation of system load average 

SYNOPSIS 

tload [-s scale] [-d delay] [tty] 

DESCRIPTION 

tioad prints a graph of the current system load average to the specified tty (orthetty of the tioad process if none is 
specified). 

OPTIONS 

The -s scale option allows a vertical scale to be specified for the display (in characters between graph ticks); thus, a smaller 
value represents a larger scale and vice versa. 

The -d delay sets the delay between graph updates in seconds. 

FILES 

/proc/ioadavg Load average information 

SEE ALSO 

ps( 1), top(l), uptime(l), w(l) 

BUGS 

The -d delay option sets the time argument for an aiarm(2); if-d 0 isspecified, the alarm is set to 0, which will never send 
thesiGALRMand update thedisplay. 

AUTHORS 

Branko Lankester, David Engel (david@ods.com), and M ichael K. Johnson (johnsonm@sunsite.unc.edu) 

CohesiveSyiems, 20 M arch 1993 


top 

top- D isplay top C PU processes 

SYNOPSIS 

top [-][ddel ay][q][S][s][i] 

DESCRIPTION 

top provides an ongoing look at processor activity in real time. It displays a listing of the most CPU-intensive tasks on the 
system, and can provide an interactive interface for manipulating processes. 
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COMMAND-LINE OPTIONS 

d Specifies the delay between screen updates. You can changethiswith the s interactive command, 

q This causes top to refresh without any delay. If thecaller has superuser privileges, top runs with the highest 

possible priority. 

s Specifiescumulativemode, where each process is listed with theCPU timethat it aswell as its dead children has 

spent. This is like the -s flag to ps(l). See the discussion of thes interactive command later in this manual page, 
s T ells top to run in secure mode. This disables the potentially dangers of the interactive commands. (See 

"InteractiveCommands," later in this manual page) A secure top isa nifty thing to leave running on a spare 
terminal. 

i Start top, ignoring any idle or zombie processes. (See the interactive command t.) 

FIELD DESCRIPTIONS 

top displays a variety of information about the processor state The display is updated every five seconds by default, but you 
can change that with the d command-line option or thes interactive command. 

uptime This line displays the time the system has been up, and the three load averages for the system. The load 

averages are the average number of process ready to run during the last 1, 5, and 15 minutes This line is 
just Iike the output of uptimef 1). 

processes Thetotal number of processes running at thetimeof the last update. T his is also broken down into the 
number of tasks that are running, sleeping, stopped, or undead. 
cpu states Shows the percentage of CPU timein user mode system mode niced tasks, and idle (N iced tasks are only 
those whose nice value is negative.) Time spent in niced tasks will also be counted in system and user 
time, so thetotal will be more than 100 percent. 

Mem Statistics on memory usage, including total available memory, free memory, used memory, shared 

memory, and memory used for buffers 

swap Statistics on swap space, including total swap space available swap space and used swap space Thisand 

Mem arejust like the output of f ree(l). 
pid The process ID of each task. 

user The username of the task's owner. 

pri T he priority of the task. 

ni The nice value of the task. Negative nice values are lower priority. 

size The size of the task's code plus data plus stack space, in kilobytes, isshown here 

rss Thetotal amount of physical memory used by the task, in kilobytes, isshown here. 

shrd The amount of shared memory used bythetask isshown in thiscolumn. 

st The state of the task isshown here. T he state is either s for sleeping, d for uninterruptible sleep, Rfor 

running, z for zombies, or t for stopped or traced. 

time TotalCPU timethetask hasused since it started. If cumulative mode ison, this also includestheCPU 

time used by the process's children that have died. You can sdt cumulative mode with thes command-line 
option or toggle it with the interactive command s. 

%cpu The task's share of theCPU time sincethe last screen update, expressed as a percentage of total CPU time. 

%mem The task's share of the physical memory. 

command The task's command name, which will be truncated if it is too long to be displayed on one line. T asks in 

memory will haveafull command line but swapped-out tasks will only have the nameof the program in 
parentheses, for example, (getty). 


INTERACTIVE COMMANDS 

Several singlekey commands are recognized while-top is running. Some are disabled if thes option has been given on the 
command line 
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■ l E rases and redraws the screen. 

h or ? D isplaysa help screen giving a brief summary of commands, and the status of secure and cumulative modes, 
k Kill a process You will be prompted for the pi d of the task, and the signal to send to it. For a normal kill, send 

signal 15. For a sure, but rather abrupt, kill, send signal 9. The default signal, as with km(l), is 15 , sigterm. 
This command is not available in secure mode, 
i Ignoreidleand zombie processes This isa toggle switch. 

n or # C hangethe number of processesto show. You will be prompted to enter the number. T hisoverrides automatic 
determination of the number of processesto show, which is based on window size measurement. If 0 isspecified, 
then top will show as many processes as will fit on the screen; this is the default, 
q Quit. 

r Renicea process You will be prompted for the pid of the task, and the value to nice it to. Entering a positive 

value will cause a process to beniced to negative values, and lose priority. If root is running top, a negative value 
can be entered, causing a process to get a higher than normal priority. The default renicevalueisio. This 
command is not avai lable in secure mode. 

s T his toggles cumulative mode, the equivalent of ps -s, in other words, that CPU timeswill include a process's 

defunct children. For someprograms, such as compilers which work by forking into many separate tasks normal 
mode will make them appear less demanding than they actually are For others, however, such as shells and tmt, 
thisbehavior iscorrect. In any case try cumulative mode for an alternative view of CPU use. 
s Change the delay between updates You will be prompted to enter the delay time in seconds, between updates 

Fractional values are recognized down to microseconds. Entering 0 causes continuous updates The default value 
is 5 seconds N otethat low values cause nearly unreadably fast displays and greatly raise the load. This command 
is not available in secure mode. 

NOTES 

Thisproc-based top works by reading the files in the proc filesystem, mounted on /proc. If /proc is not mounted, top will 
not work. 

%cpu shows the cputim^realti me percentage in the period of time between updates For the first update, a short delay is 
used,and top itself dominatestheCPU usage After that, top will drop back, and amorereliableestimateof CPU usage is 
available. 

The size and rss fields don't count the page tables and the task struct of a process thisisat least 12K of memory that is 
always resident, size isthe virtual sizeof theprocess(oode+data+stack). 

Keep in mind that a process must die for its time to be recorded on its parent by cumulative mode. Perhaps more useful 
behavior would beta follow each process upwards, adding time but that would be more expensive, possibly prohibitively so. 
In any case that would make top's behavior incompatible with ps. 

SEE ALSO 

ps( 1), f ree(l), uptime(l), kill(l), renice(l). 

BUGS 

If the window islessthan about 70x7, top will not format information correctly. 

AUTHOR 

top was originally written by Roger Binns, based on Branko Lankester's(iankeste@fwi.uva.m) ps program. Robert N ation 
(nation@rocket. sanders. iockheed.com) rewrote it significantly to use the proc filesystem, based on M ichael K. Johnson's 
(johnsonm@sunsite.unc.edu) proc-based ps program. M any changes were made, including secure and cumulative modes 
and a general cleanup, by M ichael Shields (mjshieid@nyx.cs.du.edu). 


Linux, 1 February 1993 
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touch 

touch— Change file timestamps 

SYNOPSIS 

touch [ -acfm] [-r reference-file] |-t MMDDhhmm[[CC]YY][.ss]] [-d t i me] 

[ --time={at i me, access, use, mt i me, modify}] [ --date=t i me ] [ - -f ile=r eference-fi I e] 
[■-no-create] [--help] [■-version] f i I e ... 


DESCRIPTION 

This manual page documents the GN U version of touch, touch changes the access and modification times of each given file 
to the current time. Files that do not exist are created empty. If the first filename given would be a valid argument to the-t 
option and no timestamp is given with any of the-d, -r, or -t options and the -- argument is not given, that argument is 
interpreted as the time for the other files instead of as a filename. 

If changing both the access and modification times to the current time touch can change the timestamps for files that the 
user running it does not own but has write permission for. Otherwise, the user must own the files 


OPTIONS 



- -time=modi f y 

-r, - -file reference-fi I e 
-t MMDDhhmm] | CC] YY ] [ -SS ] 

- -help 

- -version 


Change theaccess time only. 


Do not create files that do not exist. 

Uset i me (which can bein various common formats) instead of the current time Itcan 
contain month names time zones, am and pm, and so on. 

Ignored; for compatibility with BSD versions of touch. 

Change the modification timeonly. 

Use the times ofreference-fi i e instead of the current time. 

Use the argument (months days hours minutes optional century and years, optional 
seconds) instead of the current time. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output, then exit successfully. 

GNU File Utilities 


tr 

t r- T ranslate or delete characters 

SYNOPSIS 

tr [-cst] [--complement] [--squeeze-repeats] [--truncate-setl] stringl s t ring 2 
tr f-s,--squeeze-repeatsg [-c] [--complement] stringl 
tr f-d,--deleteg [-c] stringl 

tr f-d,--deleteg f-s,--squeeze-repeatsg [-c] [--complement] stringl s t rin g 2 
GNU tr also accepts the --help and - -version options 





DESCRIPTION 

This manual page documents the GN U version of tr. tr copies the standard input to the standard output, performing one 
of the following operations 

■ Translate and optionally squeeze repeated characters in the result 

■ Squeeze repeated characters 

■ Delete characters 

■ D eldte characters then squeeze repeated characters from the result. 

T he s t r i n g 1 and (if given) s t r i n g 2 arguments define ordered sets of characters referred to below as s e 11 and s e 12 . T hese 
sets are the characters of the input that tr operates on. The - -complement (-c) option replaces set 1 with itscomplement (all 
of the characters that are not in s e 11 ). 

SPECIFYING SETSOFCHARACTERS 

The format of thestri ngi andstri n g 2 arguments resembles the format of regular expressions; however, they are not regular 
expressions only lists of characters M ost characters simply represent themselves in these strings but the strings can contain 
the shorthands in the following list, for convenience. Some of them can be used only in s t r i ngi or s t r i ng 2 , as noted. 
Backslash escapes. A backslash followed by a character not listed causes an error message. 

\a Control-G 

\b Control-H 

\f Control-L 

\n Control-J 

\r Control-M 

\t Control-I 

\v Control-K 

\ 000 Thecharacter with the value given by 000 , which isl to 3 octal digits 
\n A backslash 

Ranges The notation m-n expands to all of the characters from m through n, in ascending order, m should collate before n; if 
it doesn't, an error results As an example, 0- 9 isthe same as 0123456789. Although G N U tr does not support the System 
V syntax that uses square brackets to enclose ranges, translations speci fied in that format will still work as long as the brackets 
in st ri ngi correspond to identical brackets in st r i ng 2 . 

Repeated characters. The notation [c*n] in st ri ng 2 expands to n copies of character c. Thus, [y*6] isthe same as yyyyyy. 
The notation [c*] in st ri ng 2 expands to as many copies of c as are needed to make set 2 as long asset 1 . If n begins with a 
0 , it is interpreted in octal, otherwisein decimal. 

Character classes. The notation [: class-name: ] expands to all of the characters in the (predefined) class named class- 

name. The characters expand in no particular order, except for the upper and lower classes, which expand in ascending 

order. When the - - delete (-d) and - - squeeze- repeats ( -s) options are both given, any character class can be used in 

st ri ng 2 . Otherwise only the character classes lower and upper are accepted in st ri ng 2 , and then only if the corresponding 

character class (upper and lower, respectively) is specified in the same relative position in s t ri ngi. Doing this specifies case 

conversion. The class names are given in thefollowing list; an error results when an invalid class name is given. 

ainum Letters and digits 

alpha Letters 

blank H orizontal whitespace 

cntn Control characters 

digit Digits 

graph Printablecharacters, not including space 

lower Lowercase letters 
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print Printablecharacters, including space 

punct Punctuation characters 

space Horizontal or vertical whitespace 

upper Uppercase letters 

xdigit H exadecimal digits 

Equivalence classes. The syntax [=c=] expands to all of the charactersthat are equivalent toe, in no particular order. 
Equivalence classes are a recent invention intended to support non-English alphabets But there seems to be no standard way 
to define them or determine their contents. Therefore they are not fully implemented in G N U tr; each character's 
equivalence class consists only of that character, which makes this a useless construction currently. 

TRANSLATING 

tr performs translation when st ri ngi and st ri ng2 are both given and the - -delete (-d) option is not given, tr translates 
each character of its input that is in set 1 to the corresponding character in s et 2 .Characters not in s et 1 are passed through 
unchanged. When a character appears more than once in set 1 and the corresponding characters in set 2 are not all the same 
only the final one is used. For example, these two commands are equivalent: 



tr a z 

A common use of tr isto convert lowercasecharactersto uppercase Thiscan be done in many ways H ere are three of them: 

tr abcdefghij klmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ 
tr a-z A-Z 

tr '[:lower:] 1 1 [:upper: ] 1 

When tr isperforming translation, set i and s e 12 should normally havethe same length. If s et 1 is shorter than set 2 , the 
extra characters at the end of s e 12 are ignored. 

0 n the other hand, making sett longer than set 2 is not portable; POSIX.2 says that the result is undefined. In this 
situation, the BSD tr pads s et 2 to the length of s et 1 by repeating the last character of set 2 as many times as necessary. The 
SystemV trtruncatesset 1 to the length of s e 12 . 

By default, GN U tr handles this case like the BSD tr does When the - - truncate-set 1 (-t) option is given, GN U tr 
handles this case like the System V tr instead. This option is ignored for operations other than translation. 

Acting like the System V tr in thiscasebreaksthe relatively common BSD idiom: 

tr -cs A-Za-z0-9 n012' 

because it converts only zero bytes (thefirst element in the complement of seti), rather than all nonalphanumerics to 
newlines. 

SQUEEZING REPEATS AND DELETING 

W hen given just the - -delete (-d) option, tr removes any input charactersthat are in s et 1 . 

When given just the --squeeze-repeats(-s) option, tr replaces each input sequence of a repeated character that is in set 1 
with a si ngle occurrence of that character. 

W hen given both the - -delete and the - - squeeze-repeats options, tr first performs any deletions using set 1 , then 
squeezes repeats from any remaining characters using s et 2 . 

The - -squeeze- repeats option may also be used when translating, in which case tr first performs translation, then squeezes 
repeats from any remai ning characters using s et 2 . 

H ere are some examples to illustrate various combinations of options 
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Remove all zero bytes: 

tr -d 1 n000 1 

Put all words on lines by themselves This converts all nonalphanumeric characters to newlines, then squeezes each string of 
repeated newlines into a single newline: 

tr -cs '[a-zA-Z0-9]' '[nn*]' 

Convert each sequence of repeated newlines to a single newline 


GN U tr also accepts thefollowing optionsin any combination with the others. 

- - help Print a usage message and exit with a non-zero status 

- -version Print version information on standard output, then exit. 

WARNING MESSAGES 

Setting the environment variable posixly_correct turns off several warning and error messages for strict compliance with 
POSIX.2. The messages normally occur in thefollowing circumstances: 

1. When the - -delete option isgiven but - -squeeze-repeats isnot, andstri ng2 isgiven, GNU tr by default prints a 
usage message and exits, because s t r i ng2 would notbeused.Theposixspecificationsaysthatstri ng2 must beignored 
in this case. Silently ignoring arguments is a bad idea. 

2. When an ambiguousoctal escape isgiven. For example n400isactuallyn40followedbythedigit0,becausethevalue 
400 octal does not fit into a single byte. 

NotethatGNU tr does not provide complete BSD orSystemV compatibility. For example there isno option to disable 
interpretation of thePO SIX constructs [: alpha: ], [=c=], and [ c*i 0] . Also, GNU tr does not delete zero bytes automati¬ 
cally, unlike traditional UNIX versions, which provide no way to preserve zero bytes. 

GNU Text Utilities 


tset,reset 

tset, reset— Terminal initialization 


SYNOPSIS 

tset [-IQrs] [-t] [-e ch] j-i ch] [-k ch] [-m mapping] [terminal] 


tset -V 


reset [-IQrs] [-t] [-e ch] ]-i ch] ]-k ch] ]-m mapping] [terminal] 


DESCRIPTION 

tset initializes terminals, tset first determines the type of terminal that you are using. This determination is done as 
follows, using thefirst terminal typefound: 

■ Theterminal argument specified on the command line 

■ The value of the term environmental variable 

■ Theterminal type associated with the standard error output device in the /etc/ttytype file 

■ Thedefaultterminal type, unknown 
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If the terminal type was not specified onthecommand line, the -m option mappings are then applied (see the following 
section, "Options," for more information). Then, if the terminal type begins with a question mark (?), the user is prompted 
for confirmation of the terminal type. An empty response confirms the type or, another type can be entered to specify a new 
type. After the terminal type has been determined, thetermcap entry for the terminal is retrieved. If no termcap entry is 
found for the type the user is prompted for another terminal type. 

After the termcap entry is retrieved, the window size backspace interrupt, and line kill characters (among many other 
things) are set and the terminal and tab initialization strings are sent to the standard error output. Finally, if the erase 
interrupt, and line kill characters have changed, or are not set to their default values, their values are displayed to the standard 
error output. 

When invoked as reset, tset sets cooked and echo modes, turns off cbreak and raw modes, turns on newline translation and 
resets any unset special characters to their default values before doing the terminal initialization described above This is 
useful after a program dies leaving a terminal in an abnormal state. Note you may have to type<LF>reset<LF> (the linefeed 
character is normally controi-j) to get the terminal to work, as carriage return may no longer work in the abnormal state. 
Also, the terminal will often not echo the command. 

OPTIONS 

The options are asfollows 

-t The terminal type is displayed to the standard output, and the terminal is not initialized in anyway. 

- e Set the erase character to ch. 

-i Donotsendtheterminalortab initialization strings to the terminal. 

-i Set the interrupt character to ch. 

-k Set the line kill character to ch. 

-m Specify a mapping from aporttypeto aterminal. See the following section, "Setting the Environment," for more 
information. 

-r Print the terminal type to the standard error output. 

-s Print the sequence of shell commands to initialize the environment variables columns, lines, term, and termcap 
to the standard output. 

q Don't display any values for the erase, interrupt, and line kill characters. 

-w Force setting of display size as defined in /etc/termcap file. 

-h Print short usage message 

-v Print version number. 

The arguments for the -e, -i, and - k options may either be entered as actual characters or by using the hat notation, for 
example, controi-h may be specified as" Hor" h. 

SETTING THE ENVIRONMENT 

It is often desirable to set the terminal type and information about the terminal's capabilities and display size in the shell's 
environment. This is done with the -s option; when thisoption is specified, the commands to enter the information into the 
shell's environment are output to the standard output. If the shell environmental variable ends in csh, the output 
commandsareforthecsh(l); otherwise, they are for sh(l). N ote, theoutput commands for the csh sdt and unset the shell 
variable nogiob. Thefollowing line in the .login or .profile files will initializetheenvironment correctly: 
eval 'tset -s options ... 1 

TERMINAL TYPE MAPPING 

When the terminal is not hardwired into the system (or the current system information is incorrect), the terminal type 
derived from the /etc/ttytypefileorthe term environmental variable is often something generic like network, dialup, or 
unknown. When tset is used in a startup script .profile for sh(l) users or. login for csh(l) users), it i s often desirable to 




provide information about the type of terminal used on such ports. The purpose of the -m option is to map from somesdt of 
conditions to a terminal type; that is, to tell tset, "If I’m on this port at a particular speed, guess that I'm on that kind of 
terminal." 

Theargumentto the -moption consists of an optional port type an optional operator, an optional baud rate specification, an 
optional colon (:) character, and a terminal type. The port type is a string (delimited by either the operator or the colon 
character). The operator may beany combination of: &>, &<, &@, and &i; &> means greater than, &< means less than, 
means equal to, and &i inverts the sense of the test. The baud rate is specified asa number and is compared with the speed of 
the standard error output (which should bethecontrol terminal). The terminal type isa string. 

If the terminal type is not specified on the command line, the -m mappings are applied to theterminal type. If the port type 
and baud rate match the mapping, theterminal type specified in the mapping replaces the current type If more than one 
mapping isspecified, thefirst applicable mapping is used. 

For example, consider the following: 

dialup>9600:vt100 

The port type is dialup, the operator is>, the baud rate specification is 9600, and theterminal type is vt 100 . The result of 
this mapping is to specify that if theterminal type is dialup, and the baud rate is greater than 9600 baud, a terminal type of 
vti00 will be used. 

If no port type is specified, theterminal type will match any port type; for example, 

-m dialup:vt100 -m :?xterm 

will cause any dialup port, regardless of baud rate, to match theterminal type: 

Vt100, 

and any nondialup port type to match theterminal type: 

?xterm. 

N ote, because of the leading question mark, the user will be queried on a default port as to whether they are actually using an 
xte™ terminal. 

N 0 whitespace characters are permitted in the -m option argument. Also, to avoid problems with metacharacters, it is 
suggested that the entire -m option argument be placed within single quote characters, and that csh users insert a backslash 
character (\) before any exclamation marks (1). 

ENVIRONMENT 

The tset command utilizes the shell and term environment variables, 
tset can set columns, lines, term, and termcap environmental variables 


FILES 

/etc/ttytype system Port nameto terminal type mapping database 
/etc/termcap Terminal capability database 

SEE ALSO 

csh(l), tcsh(l), sh(l),bash(l),stty(l), tty(4), termcap(5), ttytype(5), environ(7) 

HISTORY 

Thetset command appeared in BSD 3.0. 
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COMPATIBILITY 

The -a, -e, -h, -s, -u,and -v options have been deleted from thetset utility. Noneof them were documented in 4.3BSD 
and all are of limited utility at best. The -a, -d, and -poptionsare similarly not documented or useful, but were retained as 
they appear to be in widespread use. It is strongly recommended that any usage of these three options be changed to use the 
-m option instead. The -n option remains, but has no effect. It is still permissible to specify the -e, -i, and -k options 
without arguments, although it is strongly recommended that such usage be fixed to explicitly specify the character. 

Executing tset as reset no longer implies the -q option. Also, the interaction between the - option and the terminal 
argument in somehistoric implementations of tset has been removed and has been replaced with -t option. 

Finally, thetset implementation has been completely redone as part of the addition to the system of a I EE E Stdl003.1- 
1988 (PO SIX) -compliant terminal interface and will no longer compile on systems with older terminal interfaces. 

Linux, 12 January 1995 


tsort 

tsort— Topological sort of a directed graph 

SYNOPSIS 

DESCRIPTION 

tsort takes a list of pairs of node names representing directed arcs in a graph and prints the nodes in topological order on 
standard output. Input is taken from the named file, or from standard input if no file is given. 

Node names in the input are separated by whitespace, and there must bean even number of nodes. 

Presence of a node in a graph can be represented by an arc from the node to itself. This is useful when a node is not 
connected to any other nodes. 

If the graph contains a cycle (and therefore cannot be properly sorted), one of the arcs in the cycle is ignored and the sort 
continues Cycles are reported on standard error. 

SEE ALSO 

ar(l) 

HISTORY 

A tsort command appeared in AT&T v7. Thistsort command and manual page are derived from sources contributed to 
Berkeley by M ichael Rendell of M emorial U niversity of N ewfoundland. 

23 April 1991 


twm 

tv™— Tab Window M anagerfortheX Window System 

SYNTAX 

twm [ -display dpy ][-s ][-f initfile ][-v ] 

DESCRIPTION 

twm is a window manager for the X Window System. It provides titlebars shaped windows several forms of icon manage¬ 
ment, user-defined macro functions, dick-to-typeand pointer-driven keyboard focus and user-specified key and pointer 
button bindings 





This program is usually started by the user's session manager or startup script. When used frornxdm(l) or xinit(l) without a 
session manager, twm is frequently executed in the foreground as the last client. When run this way, exiting twm causes the 
session to be terminated (logged out). 

By default, application windows are surrounded by a "framed with a titlebar at the top and a special border around the 
window. The titlebar contains the window'sname, a rectangle that is lit when the window is receiving keyboard input, and 
function boxes known as t/'t/abuttonsat the left and right edges of the titlebar. 

Pressing pointer Buttonl (usually the leftmost button unless it has been changed with xmodmap) on atitlebutton will invoke 
the function associated with the button. In the default interface windows are iconified by clicking (pressing and then 
immediately releasing) the left titlebutton (which looks like a dot). Conversely, windows are deiconified by clicking in the 
associated icon or entry in the icon manager. (See description of the variable show-iconManager and of the function 

f. showiconmgr.) 

Windows are resized by pressing the right titlebutton (which resembles a group of nested squares), dragging the pointer over 
the edge that isto be moved, and releasing the pointer when the outline of the window is the desired size Similarly, windows 
are moved by pressing in the title or highlight region, dragging a window outlineto the new location, and then releasing 
when the outline is in the desired position. Just clicking in the title or highlight region raises the window without moving it. 
When new windows are created, twm will honor any size and location information requested by the user (usually through - 
geometry command-line argument or resources for the individual applications). 0 therwise, an outline of the window's 
default size its titlebar, and lines dividing the window into a 3x3 grid that track the pointer are displayed. C licking poi nter 
Buttonl will position thewindow atthecurrent position and give it the default size Pressing pointer Button2 (usually the 
middle pointer button) and dragging the outline will give the window its current position but allow the sides to be resized as 
described above. Clicking pointer Button3 (usually the right pointer button) will give the window its current position but 
attempt to make it long enough to touch the bottom of the screen. 

OPTIONS 

twm accepts the following command-line options 
-display dpy T his option specifies the x server to use. 

-s Thisoption indicates that only the default screen (as specified by -display or by the display environ¬ 

ment variable) should be managed. By default, twm will attempt to manage all screenson the display. 

-t f i i e n a me Thisoption specifiesthe nameof the startup file to use. By default, twm will look in the user's home 

directory for files named .twmrc.num (where num is a screen number) or .twmrc. 

-v Thisoption indicates that twm should print error messages whenever an unexpected X Error event is 

received. Thiscan be useful when debugging applications but can bedistracting in regular use 


CUSTOMIZATION 

M uch of twm's appearance and behavior can be controlled by providing a startup file in one of the following locations 
(searched in order for each screen being managed when twm begins): 

SHOME/.twmrc.screennuinbsr Thes c r eenn umber isa small positive number (for example, 0, i, and soon) 

representing the screen number (for example, the last number in the display 
environment variable host: dispiaynum. screennum) that would be used to contact 
that screen of the display. Thisis intended for displays with multiple screens of 
differing visual types 

$home/. twmrc This is the usual nameforan individual user's startup file. 

<xRoot>/nb/xi i / twm/system, twmrc If neither of the preceding files are found, twm will look in this file for a default 

configuration. T his is often tailored by the site administrator to provide convenient 
menus or familiar bindings for novice users <xRoot> refers to the root of the X11 
install tree. 
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If no startup files are found, twmwill use the built-in defaults described. The only resource used by twm isbitmapFiiePath 
for a colon-separated list of directories to search when looking for bitmap files For more information, see the Athena 
Widgets manual and xrdb(l). 

twm startup files are logically broken up into three types of specifications variables, Bindings, and Menus. The variables 
section must come first and is used to describe the fonts colors cursors, border widths icon and window placement, 
highlighting, autoraising, layout of titles warping, and use of the icon manager. The Bindings section usually comes second 
and is used to specify the functions that should be invoked when keyboard and pointer buttons are pressed in windows 
icons, titles and frames TheMenus section gives any user-defined menus (containing functions to be invoked or commands 
to be executed). 

Variable names and keywords are case-insensitive Strings must be surrounded by double quote characters (for example 
"blue") and are case-sensitive A pound sign (#) outside of a string causes the remainder of thelinein which thecharacter 
appears to be treated as a comment. 

VARIABLES 

M any of the aspects of twm’s user interface are controlled by variables that may beset in the user's startup file Some of the 
options are enabled or disabled simply by the presence of a particular keyword. 0 ther options require keywords, numbers, 
strings, or lists of all of these. 

Lists are surrounded by braces and are usually separated by whitespace or a newline For example, 

AutoRaise { "emacs" "XTerm" "Xmh" } 

or 

AutoRaise 


When a variable containing a list of strings representing windows is searched (for example, to determine whether or not to 
enable autoraise, as shown in the preceding example), a string must bean exact, case-sensitive match to the window's name 
(given by the wm_name window property), resource name, or class name (both given by thewM_CLAss window property). The 
preceding example would enable autoraise on windows named emacs as well asany xte™ (because they are of class xierm) or 
xmh windows (which are of class xmh). 

String arguments that are interpreted as filenames (see pixmaps, cursors, and iconDirectory in thefollowing list of 
variables) will prepend the user's directory (specified by the home environment variable) if thefirst character is a tilde ('). If, 
instead, thefirst character is a colon (:), the name is assumed to refer to one of the internal bitmapsthat are used to create 
the default titlebars symbols:: xiogo or delete (both refer to thex logo),: dot or: iconify (both refer to the dot),: resize 
(the nested squares used by the resize button),: menu (a page with lines), and: question (the question mark used for 
nonexistent bitmap files). 

Thefollowing variables may be specified at the top of a twm startup file. Lists of W indow name prefix strings are indicated by 
wi n - 1 i s t . 0 ptional arguments are shown in square brackets 

AutoRaise { win-iist ] This variable specifies a list of windowsthat should automatically be raised whenever the 
pointer enters the window. Thisaction can be interactively enabled or disabled on 
individual windows using the function f. autoraise. 

AutoReiativeResize This variable indicates that dragging out a window size (either when initially sizing the 

window with pointer Button2 or when resizing it) should not wait until the pointer has 
crossed the window edges Instead, moving the pointer automatically causes the nearest edge 
or edges to move by the same amount. T his allows the resizing of windows that extend off 
the edge of the screen. If the pointer is in the center of the window, or if the resize is begun 



Border-Color st ri ng 
windows, [{ wi ncol or I i s 


BorderTileBackground 

BorderTileForeground 

BorderWidth pi xel s 

Buttonlndent pi xel s 

ClientBorderWidth 
Color { colors-list } 


by pressing a titlebutton, twm will still wait for the pointer to cross a window edge (to 
prevent accidents). Thisoption is particularly useful for people who like the press- 
drag-release method of sweeping out window sizes. 

This variable specifies the default color of the border to be placed around all noniconified 
t >] and may only be given within acolor, Grayscale, or Monochrome list. Theoptional 
wincoioriist specifies a list of window and color namepairsfor specifying particular 
border colors for different types of windows For example: 

BorderColor 
"graySO" 

{ 

"xmh" “green" 

> 

The default is black. 

This variable specifies the default background color in the gray pattern used in st r i ng [{ 
unhighlighted borders (only if NoHighiight hasn't been set), and may only be given within 
a Color, Grayscale, Or Monochrome list. The Optional wincoioriist allows per-WindOW 
colorsto be specified. The default iswhite. 

This variable specifies the default foreground color in the gray pattern used in unhighlighted 
>] borders (only if NoHighiight hasn't been set), and may only be given within a color, 

Grayscale, Or Monochrome list. The Optional wincoioriist allows per-WindOW COlorstO be 
specified. The default is black. 

This variable specifies the width in pixels of the border surrounding all dientwindow 
frames if ciientBorderwidth has not been specified. This value is also used to set the 
border size of windows created by twm (such as the icon manager). The default is 2. 

This variable specifies the amount by which titlebuttonsshould be indented on all sides. 
Positive values cause the buttonsto be smaller than the window text and highlight area so 
that they stand out. Setting thisand thentieButtonBorderwidth variables to 0 makes 
titlebuttonsastall and wide as possible. The default is 1 . 

This variable indicates that border width of a window's frame should be sdt to the initial 
border width of the window, rather than to the value of BorderWidth. 

This variable specifies a list of color assignments to be made if the default display is capable 
of displaying more than simple black and white Thecoi or s-1 i st is made up of the 
following color variables and their values: 

DefaultBackground 
DefaultForeground 
MenuBackground 
MenuForeground 
MenuTitleBackground 
MenuTitleForeground 
MenuShadowColor 
PointerForeground 
PointerBackground 

Thefollowing color variables may also be given a list of window and color name pairs to 
allow per-window colorsto be specified (see BorderColor for details): 

BorderColor 
IconManagerHighlight 
BorderTitleBackground 
BorderTitleForeground 
TitleBackground 
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ConstrainedMoveTime 


Cursors { 


TitleForeground 
IconBackground 
IconForeground 
IconBorderColor 
IconManagerBackground 
IconManagerForeground 

For example: 

Color 

{ 

MenuBackground "gray50" 

MenuForeground "blue" 

BorderColor “red" { "XTerm" “yellow" } 

TitleForeground "yellow" 

TitleBackground "blue" 

} 

All of these color variables may also be specified for the Monochrome variable, allowing the 
same initialization file to be used on both color and monochrome displays 
This variable specifies the length of time between button clicks needed to begin a 
constrained moveperation. Double-clicking within thisamount of time when invoking 
f .move will cause the window to be moved only in a horizontal or vertical direction. Setting 
thisvalueto 0 will disable constrained moves. The default is 400 milliseconds 
This variable specifiestheglyphsthattwm should use for various pointer cursors. Each 
cursor may be defined either from the cursor font or from two bitmap files Shapes from 
the cursor font may be specified directly as 
0 cursorname "string" 

where cur sor name is one of the cursor names listed below, and s t r i n g isthenameof a 
glyph as found inthefile: 

<XRoot>/include/XI1/cursorfont.h 

(without thexc prefix). If the cursor is to be defined from bitmap files the following syntax 
is used instead: 

0 cursorname "image" "mask" 

T he i mage and mask strings specify the names of files containing the glyph image and mask 
in bitmap(l) form. T he bitmap files are located in the same manner as icon bitmap files. 

T hefollowing example shows the default cursor definitions: 

Cursors 


Title 

IconMgr 


Button 


top_left_arrow" 

top_left_arrow" 

top_left_arrow' 

top_left_arrow" 

fleur" 

fleur" 

sb_left_arrow" 


Select "dot" 

Destroy "pirate" 


DecorateTransients This variable indicates that transient windows (those containing a wm_transient_for 

property) should have titlebars. By default, transients are not reparented. 

Default Background string This variable specifies the background color to be used for sizing and information windows. 
The default iswhite. 






DefaultForeground stri ng 

DontlconifyByllnmapping 
{ win-list } 

DontMoveOff 

DontSqueezeTitle 
[{ wi n list }] 

Forcelcons 

FramePadding pi xel s 

Grayscale {colors > 

IconBackground string 


IconBorderColor stri ng 
[{ wi n-list >] 


IconBorderWidth pi xel s 

IconDirectory string 

IconFont string 

IconForeground string 
[{ wi n-list >] 


IconifyByUnmapping 
[{ wi n-list }] 


IconManagerBackground 
string [{ wi n- I i st >] 


IconManagerDontShow 
[{ wi n-list }] 


This variable specifies the foreground color to be used for sizing and information windows 
The default is black. 

Thisvariablespecifiesa list of windows that should not be iconified window (as would be 
the case if IconifyByUnmapping had been set). Thisisfrequently used to force some 
windows to be treated as icons while other windows are handled by the icon manager. 

This variable indicates that windows should not be allowed to be moved off the screen. It 
can beoverridden by the t.torcemove function. 

This variable indicates that titlebars should not be squeezed to their minimum size as 
described under squeezentie below. If the optional window list is supplied, only those 
windows wi II be prevented from being squeezed. 

This variable indicates that icon pixmaps specified in the icons variable should override any 
client-supplied pixmaps 

This variable specifies the distance between thetitlebar decorations (the button and text) 
and the wi ndow frame. T he default is 2 pixels 

This variable specifies a list of color assignments that should be made if the screen has a 
Grayscale default visual. See the description of colors. 

This variable specifies the background color of icons and may only be specified inside of a 
color, Grayscale, or Monochrome list. The optional wi n -1 i st isa list of window names and 
colors so that per-window colors may be specified. SeetheBorder-coior variablefor a 
complete description ofthewi n-1 i st . The default is white. 

This variable specifies the color of the border used for icon windows, and may only be 
specified inside of a Color, Grayscale, or Monochrome list. The Optional wi n-list isa list 
of window names and colors so that per-window colors may be specified. Seethe 
Bordercoior variablefor acomplete description ofthewi n-1 i s t . T he default is black. 

This variable specifies the width in pixels of the border surrounding icon windows. The 
default is2. 

This variable specifies the directory that should be searched if a bitmap file cannot be found 
in any of thedirectories in thebitmapFiiePath resource. 

This variable specifies the font to be used to display icon names within icons. The default is 

variable. 

This variable specifies the foreground color to be used when displaying icons, and may only 
be specified inside of a Color, Grayscale, or Monochrome list. The Optional win-list isa 
list of window names and colors so that per-window colors may be specified. Seethe 
Bordercoior variablefor a complete description of thewi n-1 i st . The default is black. 

This variable indicates that windows should beiconified by being unmapped without 
trying to map any icons. This assumes that the user will remap the window through the 
icon manager, the f.warpto function, or the Twmwindows menu. If the optional wi n-1 i st is 
provided, only those windows will beiconified by simply unmapping. Windows that have 
both thisand the iconManager Dontshow options set may not be accessible if no binding to 
the Twmwindows menu isset in the user's startup file. 

This variable specifies the background color to useforicon manager entries, and may only 
be specified inside of a color, Grayscale, or Monochrome list. The optional wi n-1 i st isa 
list of window names and colors so that per-window colors may be specified. Seethe 
Bordercoior variablefor a complete description ofthewi n-1 i st . The default is white. 

This variable indicates that the icon manager should not display any windows Ifthe 
optional wi n-1 i st is given, only thosewindows will not be displayed. This variable is used 
to prevent windows that are rarely iconified (such asxciockorxioad) from taking up 
space in the icon manager. 
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IconManagerFont stri ng 

IconManagerForeground 
string [{ wi n- I i st >] 


IconManagerGeometry 


IconManagerHighlight 
string [{ win-list }] 


IconManagers 
{ i c on mgr -1 i st > 


This variable specifies the font to be used when displaying icon manager entries The default 
is variable. 

This variable specifies the foreground color to be used when displaying icon manager 
entries, and may be specified only inside of a color, Grayscale, or Monochrome list. T he 
optional wi n-i ist isa list of window names and colors so that per-window colors may be 
specified. See the Bordercoior variable for a complete description of the wi n -1 i s t . T he 
default is black. 

This variable specifiesthe geometry of the icon manager window. Thest ri ng argument is 
standard geometry specification that indicates the initial full size of the icon manager. The 
icon manager window is then broken intocoi mens pieces and scaled according to the 
number of entries in the icon manager. Extra entries are wrapped to form additional rows. 
The default number of columns is i. 

This variable specifies the border color to be used when highlighting the icon manager entry 
that currently has the focus, and can only be specified inside of a color, Grayscale, or 
Monochrome list. The optional wi n -1 ist isa list of window namesand colors so that per- 
window colorsmay be specified. Seethe Border-color variablefor a complete description 
of thewi n -1 st .The default is black. 

This variable specifies a list of icon managers to 

create Each item in thei c on mg r -1 i st has the following format: 


IconManagerShow{ wi n-Iist 


IconRegion geomst r i ng 
vgrav hgrav gridwidth 
gr i dhei ght 


Icons { wi n- I i st > 


where wi nname isthenameof the windows that should be put into this icon manager, 
i conname isthe name of that icon manager window'sicon, geometry isastandard geometry 
specification, and c o i umns is the number of columns in this icon manager as described in 
Icon-ManagerGeometry. For example: 

IconManagers 

{ 

“XTerm" "=300x5+800+5" 5 
“myhost" "=400x5+100+5" 2 
} 

Clients whose name or class isxierm will have an entry created in thexTerm icon manager. 
Clients whose name was myhost would be put into the myhost icon manager. 

} This variable specifies a list of windows that should appear in the icon manager. When used 
in conjunction with the iconManagerDontshow variable only the windows in this list will be 
shown in the icon manager. 

This variable specifies an area on the root window in which iconsare placed if no specific 
icon location is provided by the client. Thegeomstri ng is a quoted string containing a 
standard geometry specification. If more than one IconRegion line isgiven, icons will be 
put into the succeeding icon regions when thefirst is full. The vgrav argument should be 
either North or south and is used to control whether iconsare first filled in from the 
top or bottom of the icon region. Similarly, the hgrav argument should be either East or 
west and is used to control whether iconsshould be filled in from the left or from 
the right. Iconsare laid out within the region in a grid with cellsgri dwi dth pixels wide and 
gri dhei g ht pixels high. 

This variable specifies a list of window names and the bitmap filenames that should be used 
astheir icons For example, 

Icons 


"XTerm" "xterm.icon 1 
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InterpolateMenuColors 


MakeTitle { wi n -1 i st > 
MaxWindowSize stri ng 

MenuBackground string 

MenuFont stri ng 
MenuForeground stri ng 

MenuShadowColor stri ng 

MenuTitleBackground string 

MenuTitleForeground string 

Monochrome {colors } 

MoveDelta pi xel s 

NoBackingStore 

NoCaseSensitive 

NoDefaults 

NoGrabServer 


Windows that match "XTerm" and would not be iconified by unmapping would try to use 
theicon bitmap in the file xterm. icon. If Forceicons is specified, this bitmap will be used 
even if the client has requested its own icon pixmap. 

This variable indicates that menu entry colors should be interpolated between entry 
specified colors In this example, 

Menu "mymenu" 

{ 

“Title" (“black":"red") f.title 
"entryl" f.nop 
“entry2" f.nop 

“entry3" ("white":"green") f.nop 
“entry4" f.nop 

"entry5" ("red":"white") f.nop 
> 

theforeground colorsfor "entryi" and "entry2" will be interpolated between black and 
white and the background colors between red and green. Similarly, theforeground for 
"entry4" will behalfway between white and red, and the background will behalfway 
between green and white. 

This variable specifies a list of windows on which a titie-bar should be placed and isused 
to request titles on specific windows when NoTitie has been set. 

This variablespecifiesa geometry in which the width and height give the maxi mum si ze for 
a given window. This istypically used to restrict windows to the size of the screen. The 
default width is 32767 —screen width. The default height is 32767 —screen height. 

This variable specifies the background color used for menus, and can only be specified 
inside of a Color or Monochrome list. T he default is white. 

This variable specifies the font to use when displaying menus. The default is variable. 

This variable specifies the foreground color used for menus and can only be specified inside 
Of a Color, Grayscale, Or Monochrome list. T he default is black. 

This variable specifies the color of the shadow behind pull-down menus and can only be 
specified inside of a Color, Grayscale, or Monochrome list. T he default is black. 

This variable specifies the background color fort .title entries in menus, and can only be 
specified inside of acolor, Grayscale, or Monochrome list. The default iSwhite. 

This variable specifies the foreground color fort .title entries in menus and can only be 
specified inside of a Color or Monochrome list. The default is black. 

This variable specifies a list of color assignments that should be made if the screen has a 
depth of i. See the description of colors. 

This variable specifies the number of pixels the pointer must move before the t. move 
function starts working. Also seethet .deitastop function. The default iszero pixels 
T his variable indicates that twm's menus should not request backing store to minimize 
repainting of menus This istypically used with servers that can repaint faster than they can 
handle backing store. 

This variable indicates that case should be ignored when sorting icon names in an icon 
manager. Thisoption istypically used with applicationsthat capitalizethefirst letter of 
their icon name. 

This variable indicates that twm should not supply the default titlebuttons and bindings 
Thisoption should only be used if the startup file contains a completely new set of bindings 
and definitions 

This variable indicates that twm should not grab the server when popping up menus and 
moving opaque windows. 
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NoHighlight [{ wi n-1 


NoIconManage-s 
NoMenuShadows 


NoRaiseOnDeiconify 

NoRaiseOnMove 

NoRaiseOnResize 


NoRaiseOnWarp 


NoSaveUnders 


NoStackMode [{ wi n-1 


st }] This variable indicates that borders should not be highlighted to track the location of the 
pointer. If the optional wi n-i ist isgiven, highlighting will only be disabled for those 
windows. When the border is highlighted, it will be drawn in the current Border-color. 

W hen the border is not highlighted, it will be stippled with a gray pattern using the current 
BorderTileForeground and BorderTileBack-ground Colors 
This variable indicates that no icon manager should be created. 

This variable indicates that menus should not have drop shadows drawn behind them. This 
is typically used with slower servers because it speeds up menu drawing at the expense of 
making the menu slightly harder to read. 

This variable indicates that windows that are deiconified should not be raised. 

This variable indicates that windows should not be raised when moved. This is typically 
used to allow windows to slide underneath each other. 

This variable indicates that windows should not be raised when resized. This istypically 
used to allow windows to be resized underneath each other. 

This variable indicates that windows should not be raised when the pointer iswarped into 
them with the f .warpto function. If this option isset, warping to an occluded window may 
result in the pointer ending up in the occluding window instead the desired window, which 
causes unexpected behavior with t.warpring. 

This variable indicates that menus should not request save-unders to minimize window 
repainting following menu selection. It istypically used with displays that can repaint faster 
than they can handle save-unders 

st }] This variable indicates that client window requests to change stacking order should be 

ignored. If the optional wi n -1 ist isgiven, only requests on those windows will be ignored. 
This istypically used to prevent applicationsfrom relentlessly popping themselves to the 
front of the window stack. 


NoTitle [{ wi n- I i st }] 


NoTitleFocus 


NoTitleHighlight 
[{ wi n-list }] 


OpaqueMove 


Pixmaps { pi xmaps } 


Priority priority 
RandomPlacement 


This variable indicates that windows should not have title-bars. If the optional wi n -1 ist is 
given, only those windows will not have titlebars Makentie may be used with this option 
to force titlebars to be put on specific windows. 

This variable indicates that twm should not set keyboard input focus to each window as it is 
entered. Normally, twm sets the focus so that focus and key events from the titlebar and icon 
managers are delivered to the application. If the pointer is moved quickly and twm is slow to 
respond, input can be directed to the old window instead of the new. This option is 
typically usai to prevent this input lag and to work around bugs in older applications that 
haveproblemswith focus events. 

This variable indicates that thehighlight area of thetitlebar, which isused to indicate the 
window that currently has the input focus, should not be displayed. If the optional wi n- 
i i st isgiven, only those windows will not have highlight areas. Thisandthesqueezentie 
options can be set to substantially reduce the amount of screen space required by titlebars. 
Thisvariableindicatesthatthef. move function should actually move the window instead of 
just an outline so that the user can immediately see what the window will look like in the 
new position. This option istypically used on fast displays (particularly if NoGrabServer is 
set). 

This variable specifies a I ist of pixmaps that define the appearance of various i mages E ach 
entry isa keyword indicating the pixmap to set, followed by a string giving the name of the 
bitmap file. The following pixmaps may be specified: 0 pixmaps { TitieHighiight 
"grayl" > 

The default for TitieHighiight is to use an even stipple pattern. 

This variable sets twm’s priority, priority should bean unquoted, signed number (for 
example, 999). This variable has an effect only if theserver supports the SYN C extension. 
This variable indicates that windows with no specified geometry should be placed in a 
pseudorandom location instead of having theuser drag out an outline. 



ResizeFont string This variable specifiesthe font to be used for in the dimensions window when resizing 

windows. The default is fixed. 

RestartPreviousstate This variable indicatesthat twm should attempt to usethewM_sTATE property on client 

windows to tell which windows should beiconified and which should be left visible This is 
typically used to try to regenerate the state that the screen was in before the previous 
window manager was shutdown. 

saveCoior { colors-list > This variable indicates a list of color assignments to be stored as pixel values in the root 

window property _mit_priority_colors. C lients may elect to preserve these values when 
installing their own colormaps Note that use of this mechanism is a way for an application 
to avoid the "technicolor" problem, whereby useful screen objects such as window borders 
and titlebars disappear when a program's custom colors are installed by the window 
manager. For example 

SaveCoior 

{ 

BorderColor 
TitleBackground 
TitleForeground 


"green" 


ShowIconManager 

SortlconManager 

SqueezeTitle 
[{ squeeze-list >] 


Startlconified 


TitleBackground string 
[{ wi n-list }] 

TitleButtonBorderWidth 


This would placeon the root window three pixel values for borders and titlebars, as well as 
the three color strings, all taken from the default colormap. 

This variable indicates that the icon manager window should be displayed when twm is 
started. It can always be brought up using the f.showiconmgr function. 

This variable indicates that entriesin the icon manager should be sorted alphabetically 
rather than by simply appending new windows to the end. 

This variable indicates that twm should attempt to use the shape extension to make titlebars 
occupy only as much screen space as they need, rather than extending all the way across the 
top of the window. Theoptional squeeze -1 i st may be used to control the location of the 
squeezed titlebar along the top of the window. It contains entries of the form: 0" name - 
justification nu m d eftoW Where n a me is a window name, j ustification is either left, 
center, or right, and n u m and d e no m are numbers specifying a ratio giving the relative 
position about which the titlebar is justified. The ratio is measured from left to right if the 
numerator is positive, and right to left if negative A denominator of 0 indicatesthat the 
numerator should be measured in pixels For convenience the ratio 0/0 is the same as 1/2 
for center and -1/1 for right. For example 

SqueezeTitle { "XTerm" left 0 0 "xterml" left 1 3 "xterm2" left 2 3 
"oclock" center 0 0 “emacs" right 00} 

The DontsqueezeTitie list can beused to turn off squeezing on certain titles. 

This variable indicates that client windows should initially be left as icons until explicitly 
deiconified by the user. If the optional wi n-1 i st isgiven, only those windows will be 
started iconic. This is useful for programs that do not support an -iconic command-line 
option or resource 

This variable specifies the background color used in titlebars, and may only be specified 
inside of a Color, Grayscale, Or Monochrome list. The Optional wi n -1 i st is a list Of window 
names and colors so that per-window colors may be specified. The default iswhite. 

This variable specifiesthe width in pixels of the border surrounding titlebuttons T his is 
typically set to 0 to allow titlebuttons to take up as much space as possible and to not have a 
border. The default is 1. 
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TitleFont st ring 

TitleForeground string 
[{ wi n-list }] 

TitlePadding pi xel s 

Unknownlcon st rlng 

UsePPosition stri ng 


WarpCursor [{ wi n- 1 ist }] 


WindowRing { wi n- I i s t } 
WarpUnmapped 


XorValue number 


This variable specifies the font to be used for displaying window names in titlebars. The 
default iSvariable. 

This variable specifies the foreground color used in titlebars, and may only be specified 
inside of a Color, Grayscale, Or Monochrome list. The Optional wi n -1 i st is a list Of window 
names and colors so that per-window colors may be specified. The default is black. 

This variable specifies the distance between the various buttons, text, and highlight areas in 
thetitlebar. The default iss pixels. 

This variable specifiesthe filename of a bitmap file to be used asthedefault icon. This 
bitmap will be used as the icon of all clients that do not provide an icon bitmap and are not 
listed in the icons list. 

This variable specifies whether or nottwm should honor program-requested locations (given 
by thepposition flag in the wm_normal_hints property) in the absence of a user-specified 
position. The argument stri ng may have one of three values: off (the default), indicating 
that twm should ignore the program-supplied position; on, indicating that the position 
should be used; and non-zero, indicating that the position should used if it is other than 
(0,0). The latter option is for working around a bug in older toolkits 
This variable indicates that thepointer should be warped into windows when they are 
deiconified. If the optional wi n-i ist is given, thepointer will only be warped when those 
windows are deiconified. 

This variable specifies a list of windows along which thef. warpring function cycles 
Thisvariableindicatesthatthef .warpto function should deiconify any iconified windows 
it encounters This istypically used to make a key binding that will pop up a particular 
window (such asxmh) no matter where it is. T hedefault isfor f .warpto to ignore iconified 
windows. 

This variable specifies the value to use when drawing window outlinesfor moving and 
resizing. This should be set to a value that will result in a variety of distinguishable colors 
when exclusive or isused with the contents of the user's typical screen. Setting this variable 
to 1 often gives nice results if adjacent colors in the default colormap are distinct. By 
default, twm will attempt to cause temporary lines to appear at the opposite end of the 
colormap from the graphics 

This variable indicates that outlines suggesting movement of a window to and from its 
iconified state should be displayed whenever a window is iconified or deiconified. T he 
optional count argument specifiesthe number of outlines to be drawn. The default count 
iss. 


Thefollowing variables must beset after the fonts have been assigned, so it is usually best to put them at the end of the 
variables or at the beginning of the bindi ngs sections 

DefauitFunction function This variable specifies the function to be executed when a key or button event is received for 

which no binding is provided. This istypically bound to f. nop, f .beep, or a menu 
containing window operations. 

windowFunction function This variable specifies the function to execute when a window is selected from the 

Twmwindows menu. If this variable is not set, the window will be deiconified and raised. 


BINDINGS 

After the desired variables have been set, functions may be attached ti tlebuttons and key and pointer buttons Titlebuttons 
may be added from the left or right side and appear in the titlebar from left to right according to the order in which they are 
specified. Key and pointer button bindings may be given in any order. 

Titlebuttons' specifications must include the nameof the pixmap to use in the button box and the function to be invoked 
when a pointer button is pressed within them: 
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0 LeftTitleButton "bi tmapname"=funct i on 


or 

0 RightTitleButton "bi t mapname|^$§||i^#j|j;. 

Thebi t mapname may refer to one of the built-in bitmaps (which are scaled to match mie-Font) by using the appropriate 
colon-prefixed name described earlier. 

Key and pointer button specifications must give the modifiers that must be pressed, over which parts of the screen the 
pointer must be, and what function isto be invoked. Keys are given as strings containing the appropriate keysym name; 
buttons are given aSthekeyWOrdSButtonl-Button5: 0 "FP1 m = modi i st : context : function Buttonl = modi i st : 

The mod 1 i st is any combination of the modifier names shift, control, lock, meta, modi, mod2, mod3, mod4, or mods (which 
may be abbreviated ass, c, 1, m, mi, m2, m3, m4, ms, respectively) separated by a vertical bar (|). Similarly, thee 0 nt ext is any 
combination of window, title, icon, root, frame, iconmgr, their first letters (iconmgr abbreviation ism), or aii, separated 
by a vertical bar. The function isany of the f keywords described in thefollowing list. For example, the default startup file 
contains the following bindings: 

Buttonl = : root : f.menu “TwmWindows" 

Buttonl = m : window ] icon : f.function "move-or-lower" 

Button2 = m : window ] icon : f.iconify 

Button3 = m : window ] icon : f.function "move-or-raise" 

Buttonl = : title : f.function “move-or-raise" 

Button2 = : title : f.raiselower 

Buttonl = : icon : f.function "move-or-iconify" 

Button2 = : icon : f.iconify 
Buttonl = : iconmgr : f.iconify 
Button2 = : iconmgr : f.iconify 

A user who wanted to be able to manipulate windows from the keyboard could use the following bindings 

“FI" = : all : f.iconify 

"F2" = : all : f.raiselower 

“F3" = : all : f.warpring "next" 

"F4" = : all : f.warpto "xmh" 

"F5“ = : all : f.warpto "emacs" 

"F6" = : all : f.colormap “next" 

"F7“ = : all : f.colormap “default" 

"F20" = : all : f.warptoscreen “next" 

“Left" = m : all : f.backiconmgr 
"Right" = m | s : all : f.forwiconmgr 
"Up" = m : all : f.upiconmgr 
"Down" = m | s : all : f.downiconmgr 

twm provides many more window manipulation primitives than can be conveniently stored in a titlebar, menu, orsdtof key 
bindings. Although asmall set of defaults is supplied (unless the NoDefauits is specified), most users will want to have their 
most common operations bound to key and button strokes. To do this twm associates names with each of the primitives and 
provides user-defined functionsfor building higher level primitives and menus for interactively selecting among groups of 
functions 
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U ser-defined functions contain the name by which they are referenced in calls to f. function and a list of other functions to 
execute For example, 


Function "move-or-lower“ { f.move f.deltastop f.lower } 

Function "move-or-raise" { f.move f.deltastop f.raise } 

Function “move-or-iconify" { f.move f.deltastop f.iconify } 

Function “restore-colormap" { f.colormap "default" f.lower } 

Thefunction name must be used in f. function exactly as it appears in thefunction specification. 

In the following descriptions, if thefunction is said to operate on the selected window, but is invoked from a root menu, the 
cursor will be changed to the Select cursor and the next window to receive a button press will be chosen: 


f.bottomzoom 

f. circledown 

f.colormap stri ng 


f .deiconify 


f.delete 


f.deltastop 


f.destroy 


f.downiconmgr 




This is an abbreviation fort .exec string. 

This function toggles whether or not the selected window is raised whenever entered by the 
pointer. See the description of the variable AutoRaise. 

This function warps the pointer to the pre/ious column in the current icon manager, 
wrapping back to the previous row if necessary. 

This function sounds the keyboard bell. 

This function is similar to the f .fuiizoom function, but resizesthewindow to fill only the 
bottom half ofthescreen. 

This function lowers the topmost window that occludes another window. 

Thisfunction raises the bottommost window that is occluded by another window. 

This function rotates the colormaps (obtained from thewM_coLORMAP_wiNDows property on 
the window) that twm will display when the pointer is in this window. T heargument 
string may have one of the following values: next, prev, and default. It should be noted 
here that in general, the installed colormap isdetermined by keyboard focus A pointer- 
driven keyboard focus will install a private colormap upon entry of the window owning the 
colormap. Using thedick-to-type model, private colormaps will not be installed until the 
user clicks on the target window. 

Thisfunction deiconifies the selected window. If the window isnot an icon, thisfunction 
does nothing. 

Thisfunction sends the wm_delete_window message to the selected window if the client 
application has requested it through thewM_PR0T0C0L.s window property. The application is 
supposed to respond to the message by removing the indicated window. If the window has 
not requested wm_delete_window messages, the keyboard bell will be rung, indicating that 
the user should choose an alternative method. N ote this is very different from f .destroy. 
The intent here is to deldte a single window, not necessarily the entire application. 
Thisfunction allows a user-defined function to be aborted if the pointer has been moved 
more than MoveDeita pixels See the example definition given for Function “move-or- 
raise" atthebeginningofthesection. 

Thisfunction instructs the x server to close the display connection of the client that created 
the selected window. This should only be used as a last resort for shutting down runaway 
clients. See also f .delete. 

Thisfunction warps the pointer to the next row in the current icon manger, wrapping to 
the beginning of the next column if necessary. 

Thisfunction passestheargument string to /bin/sh for execution. In multiscreen mode 
if s t r i ng starts a new x client without giving a display argument, the client will appear on 
the screen from which thisfunction was invoked. 

Thisfunction toggles the keyboard focus of the server to the selected window, changing the 
focus rule from pointer-driven if necessary. If the selected window already was focused, this 
function executes an t. unfocus. 
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Thisfunction is like f. move except that it ignores the DontMoveOf f variable 
Thisfunction warps the pointer to the next column in the current icon manager, wrapping 
to the beginning of the next row if necessary. 

T his function resizes the selected window to the full size of the display or else restores the 
original size if the window was already zoomed. 

Thisfunction executes the user-defined function whose name is specified by the argument 

T his function is a synonym for f. bottomzoom. 

Thisfunction unmaps the current icon manager. 

This variable is similar to the f. zoom function except that the selected window is resized to 
thefull width of the display. 

T his function is a synonym for f. topzoom. 

Thisfunction is a synonym forf .horizoom. 

Thisfunction iconifies or deiconifies the selected window or icon, respectively. 

Thisfunction displays a summary of the name and geometry of the selected window. If the 
server supports the sync extension, the priority of theclient owning the window is also 
displayed. Clicking the pointer or pressing a key in the window will dismiss it. 

This function is similar to f. backiconmgr except that wrapping does not change rows 
This variable is similar to the f. bottomzoom function but causes the selected window to be 
resized only on the left half of the display. 

Thisfunction lowers the selected window. 

Thisfunction invokes the menu specified by the argument s t r i ng. Cascaded menus may be 
built by nesting calls to f. menu. 

Thisfunction drags an outline of the selected window (or the window itself if the 
opaqueMove variable is set) until the invoking pointer button is released. Double-clicking 
within the number of milliseconds given by constrainedMoveTime warps the pointer to the 
center of the window and constrainsthemoveto be either horizontal or vertical, depending 
on which grid line is crossed. To abort amove, press another button before releasing the 
first button. 

Thisfunction warps the pointer to the next icon manager containing any windowson the 
current or any succeedi ng screen. 

Thisfunction does nothing and is typically used with the Default-Function or 
windowFunction variablesor to introduce blank lines in menus. 

Thisfunction warps the pointer to the previous icon manager containing any windowson 
the current or preceding screens. 

Thisfunction sets the priority of theclient owning the selected window to the numeric 
value of the argument st r i ng, which should be a signed integer in double quotes (for 
example, "999"). Thisfunction has an effect only if theserver supports thesYNC extension. 
Thisfunction causes twm to restore the window's borders and exit. If twm is the first client 
invoked from xdm, this will result in a server reset. 

Thisfunction raises the selected window. 

Thisfunction raises the selected window to the top of the stacking order if it isocduded by 
any wi ndows; otherwise, the window is lowered. 

Thisfunction causes all windows to be refreshed. 

Thisfunction displays an outline of the selected window. Crossing a border (or setting 
AutoReiativeResize) will causetheoutlineto begin to rubber band until theinvoking 
button is released. To abort a resize, press another button before releasing the first button. 
Thisfunction kills and restarts twm. 

Thisfunction is similar to f. nexticonmgr except that wrapping does not change rows 
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f .rightzoom 
f. saveyourself 


showiconmgr 

sorticonmgr 


f .title 

f .topzoom 

f. unfocus 

f. upiconmgr 

f.vlzoom 
f.vrzoom 

f.warpring stri ng 
f.warpto string 


f.warptoiconmgr stri ng 


f.warptoscreen string 


This variable is similar to the f. bottomzoom function except that the selected window is 
only resized to the right half of the display. 

Thisfunction sends a wm_saveyourself message to the selected window if it has requested 
themessagein its wm_protocols window property. Clients that accept thismessage are 
supposed to checkpoint all states associated with thewindow and update the wm_command 
property as specified in the icccm. If the selected window has not been selected for this 
message, the keyboard bell will be rung. 

Thisfunction maps the current icon manager. 

Thisfunction sorts the entries in the current icon manager alphabetically. See the variable 

SortlconManager. 

Thisfunction provides a centered, unselectableitem in a menu definition. It should not be 
used in any other context. 

This variable is similar to the f. bottomzoom function except that the selected window is 
only resized to the top half of the display. 

Thisfunction resetsthefocusbackto pointer-driven. This should be used when afocused 
window is no longer desi red. 

Thisfunction warps the pointer to the previous row in the current icon manager, wrapping 
to the last row in the same column if necessary. 

Thisfunction is a synonym fort .leftzoom. 

This function is a synonym for f. rightzoom. 

Thisfunction warps the pointer to the next or previous window (asindicated by the 
argument st ri ng, which maybe "next" or "prev") specified in thewindowRing variable 
Thisfunction warps the pointer to thewindow that has a nameor class that matches 
string. If thewindow is iconified, it will bedeiconified if the variable warpunmapped is set 
or else ignored. 

Thisfunction warps the pointer to the icon manager entry associated with thewindow 
containingthepointerintheicon manager specified by the argument s t r i ng. If stri ng is 
empty (that is, 11 "), thecurrent icon manager ischosen. 

Thisfunction warps the pointer to the screen specified by the argument s t r i ng. stri ng 
may be a number (such as'V or "i”), the word - next" (indicating the current screen plus 
1, skipping over any unmanaged screens), the word "back” (indicating the current screen 
minus 1, skipping over any unmanaged screens), or the word ■ prev (indicating the last 
screen visited. 

Thisfunction is similar to the f. refresh function except that only the selected window is 
refreshed. 

Thisfunction is similar to the f. f uiizoom function, except that only the height of the 
selected window is changed. 


MENUS 

Functions may be grouped and interactively selected using pop-up (when bound to a pointer button) or pull-down (when 
associated with atitlebutton) menus Each menu specification contains the name of the menu as it will be referred to by 
f .menu, optional default foreground and background colors the list of item names and thefunctions they should invoke, 
and optional foreground and background colors for individual items: 

[ ("f o r e 2 ■ : 1 bJtled 1) ] function ...stringN [ ("f o r eN " : "backN “) ] functionN } 

Themenuname i s case-sensitive. Theoptional deffore and defback arguments specify the foreground and background colors 
used on a color display to highlight menu entries The string portion of each menu entry will be the text that will appear in 
the menu. Theoptional fore and back arguments specify the foreground and background colors of the menu entry when the 
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pointer is not in the entry. These colors will only be used on a color display. The default is to use the colors specified by the 
MenuForeground and MenuBackground variables The function portion of the menu entry is one of thefunctions including 
any user-defined functions, or additional menus. 

There is a special menu named Twmwindows that containsthe names of all ofthedient and twm-supplied windows Selecting 
an entry will cause the windowFunction to be executed on that window. If windowFunction hasn't been set, the window will 
be deiconified and raised. 

ICONS 

twm supports several different ways of manipulating iconified windows The common pixmap-and-text style may be laid out 
by hand or automatically arranged as described by theiconRegion variable. In addition, a terse grid of icon names, called an 
icon manager, provides a more efficient use of screen space as well as the ability to navigate among windows from the 
keyboard. 

An icon manager is a window that contains names of selected windows or all windows currently on the display. In addition 
to the window name a small button using the default iconify symbol will be displayed to the left of the name when the 
window is iconified. By default, clicking on an entry in the icon manager performs f .iconify. T o change the actions taken 
in the icon manager, use the iconmgr context when specifying button and keyboard bindings 

If you move the pointer into the icon manager, the keyboard focus is also directed to the indicated window (setting the focus 
explicitly or else sending synthetic events NoTitleFocus is set). Using thef .upiconmgr, f .downiconmgr, f .lefticonmgr, 
and f.nghticonmgr functions the input focus can be changed between windows directly from the keyboard. 

BUGS 

The resource manager should have been used instead of all of the window lists. 

The iconRegion variable should take a list. 

Double-clicking very fast to get the constrained move function will sometimes cause the window to move, even though the 
pointer is not moved. 

If IconifyByUnmapping ison and windows are listed in IconManagerDontShow but not in DontlconifyByUnmapping, they 
may be lost if they are iconified and no bindings to f .menu "Twmwindows" orf .warpto are setup. 

FILES 

$HOME/.twmrc.<screen number> 

$H0ME/.twmrc 

<XRoot>/lib/X11/twm/system.twmrc 

ENVIRONMENT VARIABLES 

display This variable is used to determine which x server to use It is also set during f. exec so that programs come up on 
the proper screen. 

home This variable is used as the prefix for files that begin with a tilde and for locating the twm startup file. 

SEE ALSO 

X(l), Xserver(l), xdm(l), xrdb(l) 

AUTHORS 

Tom LaStrange, SolbourneComputer; Jim Fulton, M IT X Consortium; StevePitschke, Stardent Computer; Keith Packard, 
M IT X Consortium; DavePayne Apple Computer. 

SEE ALSO 

X(l), Xserver(l), x 


X Version 11 Release 6 
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txt2gcal 

txt2gcai-Creates a verbatim gcai resource filefrom atext file 

SYNOPSIS 

txt2gcal [ --help | --version ] \ [ Text-file | - ] [Dat e-part ] 

DESCRIPTION 

txt2gcai is a program that createsa verbatim gcairesourcefilefromatextfile. If no t ext - f i i e or - argument is given, the 
program reads and processes all input received from the standard input channel. If no date - part argument isgiven, 
txt2gcai creates a 0 for the date part. All results are always shown on the standard output channel. An exit status of 0 means 
all processing is successfully done; any other value means an error has occurred. 

OPTIONS 

--help Print a usage message listing all available options, then exit successfully. 

- -version Print the version number, then exit successfully. 


COPYRIGHT 

Copyright© 1996 Thomas Esken. This software doesn't claim completeness, correctness, or usability. On principle, I will not 
be liable for any damagesor losses (implicit or explicit), which result from using or handling my software If you use this 
software, you agree without any exception to this agreement, which binds you legally. 

txt2cai is free software and distributed under the terms of theGN U General Public License; published by the Free Software 
Foundation; version 2 or (at your option) any later version. 

Any suggestions, improvements, extensions, bug reports, donations, proposalsfor contract work, and so forth are welcome. If 
you likethistool, I'd appreciate a postcard from you! 

Enjoy it =8 A ) 

AUTHOR 

ThomasEsken (esken@uni-muenster.de) 
m FI agenfeld 84 
D-48147 M uenster; Germany 
Phone:+49 251 232585 


SEE ALSO 

gcal(l), tcal(l) 


16 July 1996 


Ul 

ul— Do underlining 

SYNOPSIS 

ul t-1] [-t terminal] [name ...] 

DESCRIPTION 

ui reads the named files (or standard input if none are given) and translates occurrences of underscores to thesequence that 
indicates underlining for theterminal in use, as specified by the environment variableiERM . The file /etc/termcapisreadto 
determine the appropriate sequences for underlining. If theterminal is incapable of underlining but is capable of a standout 
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mode then that isused instead. If the terminal can overstrike or handles underlining automatically, ui degenerates to 
cat(l). If the terminal cannot underline underlining is ignored. 

Thefollowing options are available: 

-i Underlining is indicated by a separate line containing appropriate dashes this is useful when you want to 

look at the underlining which is present in an nroff output stream on a CRT terminal. 

-t terminal 0 verrides the terminal type specified in the environment with terminal. 

ENVIRONMENT 

Thefollowing environment variable is used 

term Relatesa tty device with its devicecapability description; see termcap(5). term isset at login time, either 

by the default terminal type specified in /etc/ttys or asset during the login process by the user in the 
login file; see setenv(l). 


SEE ALSO 

man(l), nroff(l), colcrt(l) 

BUGS 

nroff usually outputs a series of backspaces and underlines intermixed with the text to indicate underlining. No attempt is 
made to optimize the backward motion. 

HISTORY 

The ui command appeared in BSD 3.0. 

BSD 4, 6Junel993 


unexpand 

unexpand- Convert spaces to tabs 

SYNOPSIS 

unexpand [-tabl[ ,tab2[,...]]] [-t tabl [ ,tab2[,...]]] [-a][■-tabs=tabl[,tab2 [,...]]] 

[--all] [--help] [--version] [file...] 

DESCRIPTION 

This manual page documents the G N U version of unexpand, unexpand writes the contents of each given file or the standard 
input if none are given or when a file named - is given, to the standard output, with strings of two or more space or tab 
characters converted to as many tabs as possible followed by as many spaces as are needed. By default, unexpand converts 
only initial spaces and tabs (those that precede all characters that aren't spaces or tabs) on each line. It preserves backspace 
characters in the output; they decrement the column count for tab calculations. By default, tabs are set at every 8th column. 

OPTIONS 

-, -t, --tabs tabi[,tab 2 [,...]] If only one tab stop isgiven, set the tabst a bi spaces apart instead of the default s. 

Otherwise, set thetabs at columns t a bi, t a b 2 , and so on (numbered from 0 ) and 
leave spaces and tabs beyond the tab stops given unchanged. If the tab stops are 
specified with the -t or - -tabs option, they can be separated by blanks as well as by 
commas. This option implies the -a option. 

-a, - -an Convert all strings of two or more spaces or tabs, not just initial ones, to tabs. 

- - help Print a usage message and exit with a non-zero status 

- -version Print version information on standard output, then exit. 


GNU Text Utilities 
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uniq 

uniq— Remove duplicate lines from a sorted file 

SYNOPSIS 

uniq [-cdu] [-f skip-fields] [-s skip-chars] ]-w check-chars] [-#skip-fields] 

[+#skip-chars] [--count] [--repeated] [--unique] [--skip-fields=skip-fields] 

]--skip-chars=skip-chars] [--check-chars=check-chars] [--help] [--version] 

[infile] [outfile] 

DESCRIPTION 

This manual page documents the GN U version of uniq. uniq prints the unique lines in a sorted file, discarding all but one of 
a run of matching lines. It can optionally show only lines that appear exactly once or lines that appear more than once, uniq 
requires sorted input because it compares only consecutive lines 

If the output file is not specified, uniq writes to the standard output. Iftheinput file is not specified, it reads from the 
standard input. 

OPTIONS 

-u, - - unique 
-d, --repeated 

-number , -f, 

--skip-fields=number 


+n u mb e r , - s, 

--skip-chars=number 


--check-chars=number 

--version 


unshar 

unshar—Unpack a shar file 

SYNOPSIS 

unshar [ -d di rectory ] [ -c ][-e | -E exit_line ] [file ... ] 

DESCRIPTION 

unshar scans mail messages looking for the start of a shell archive It then passes the archive through acopy of the shell 
to unpack it. It will accept multiple files If no files are given, standard input is used. This manual page reflects unshar 
version 4.0. 


Only print unique lines 
Only print duplicate lines 

Print the number of times each line occurred along with the line 
In this option, number isan integer representing the number of fields to skip over 
before checking for uniqueness Thefirst n u mbe r fields, along with any blanks 
found before number fields is reached, are skipped over and not counted. Fields are 
defined as a strings of nonspace, nontab characters that are separated from each 
other by spaces and tabs 

In this option, number isan integer representing the number of characters to skip 
over before checking for uniqueness Thefirst number characters along with any 
blanks found before number characters is reached, are skipped over and not counted. 

If you use both the field and character skipping options, fields are skipped over first. 

Specify the number of characters to compare in the lines after skipping any specified fields 
and characters. N ormally, the entire remainder of the lines are compared. 

Print a usage message and exit with a non-zero status 
Print version information on standard output, then exit. 

GNU Text Utilities 




OPTIONS 

Options have a one-letter version starting with - ora long version starting with The exceptions are --help and -- 
version, which don't have a short version. 


- -version 

- -help 

-d Dl RECTORY 

- -directory=DI RECTORY 
-c --overwrite 


Print the version number of the program on standard output, then immediately exit. 

Print a help summary on standard output, then immediately exit. 

Change directory to Dl RECTORY 
before unpacking any files. 

Passed as an option tothesharfile M any shell archive scripts (including those produced by 
shar 3.40 and newer) accept a -c argument to indicate that existing files should be 
overwritten. 

This option exists mainly for people who collect many shell archives into a single mail 
folder. With this option, unshar isolates each different shell archive from the others that 
have been put in the same file, unpacking each in turn, from the beginning of thefile 
towards its end. Its proper operation relies on the fact that many shar files are terminated 
by an exit 0 at the beginning of a line. 

Option -e is i nternally equivalent to -e "exit 0“. 

Thisoption works like -e, but it allows you to specify thestringthat separates archives 
if exit 0 isn't appropriate. For example noticing that most .signatures have a -- 
on a line right before them, one can sometimes use - - split-at=- - for splitting shell 
archivesthat lack the exit 0 line at end. Thesignature will then be skipped altogether with 
the headers of thefollowing message 


SEE ALSO 

shar(l) 

DIAGNOSTICS 

Any message from the shell may be displayed. 


AUTHORS 

M ichael M auldin at CarnegieM ellon University, Guido van Rossum atCWI, Amsterdam (guido@mcvax), Bill Davidsen 
(davidsen@sixhub.uuxp), Warren Tucker (wht%n4hgf@gatech.edu) 

Richard H. Gumpertz (rhg@cps.coM), and Colas Nahaboo (coias@avahi.inria.fr). M an pages by Jan Djfrv 
(jhd@irfu.se). 

12 August 1990 


updatedb 

updatedb— U pdate a filename database 

SYNOPSIS 

updatedb [opt ions] 

DESCRIPTION 

This manual page documents the GN U version of updatedb, which updates filename databases used byGN U locate. The 
filenamedatabases contain lists of files that werein particular directory trees when the databases were last updated. The 
filename of the default database is determined when locate and updatedb are configured and installed. The frequency with 
which the databases and the directories for which they contain entries are updated depends on how often updatedb is run, 
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and with which arguments. In networked environments, it often makes sense to build a database at the root of each 
filesystem, containing the entries for that filesystem. To prevent thrashing the network, updatedb is then run for each 
filesystem on the fileserver where that filesystem ison alocal disk. Users can select which databases locate searches using an 
environment variable or command-line option; see locate(lL). Databases can not be concatenated together. The filename 
database format changed starting with GNU find and locate version 4.0 to allow machines with different byte orderings to 
share the databases. T he new G N U locate can read both the old and new database formats. H owever, old versions of 
locate and find produce incorrect results if given a new-format database. 

OPTIONS 

- - iooaipaths='pat hi pat h2... 1 Nonnetwork directories to putin the database. Default is/. 

- - netpaths='pat hi pat h2... 1 Network (nfs, afs, rfs, and so on) directories to put in the database Default is 


--prunepaths='pathi pat h2 ... 1 

- -output=dbf i I e 

--netuser=user 
--old-format 

- -version 


D irectoriesto not put in thedatabase, which would otherwise be put there. D efault 

is/tmp /usr/tmp /var/tmp /afs. 

Thedatabase file to build. Default is system-dependent, but typically/usr/iocai/ 
var/locatedb. 

The user to search network directories as, using su(l). Default isdaemon. 

C reate the database i n the old format instead of the new one. 

Print the version number of updatedb and exit. 

Print a summary of theoptionsto updatedb and exit. 


SEE ALSO 

find(lL), locate(lL), iocatedb(5L), xargs(lL) F/ncf/ngF//es(onlinein info, or printed) 

uptime 

uptime-Tel I how long the system has been running 

SYNOPSIS 

uptime 

DESCRIPTION 

uptime givesa one-line display of the information that follows it: the current time how long the system has been running, 
how many users are currently logged on, and thesystem load averages for the past 1, 5, and 15 minutes 
Thisisthesameinformation contained in the header linedisplayed by w(l). 

FILES 

/var/run/utmp Information about who is currently logged on 
/proc Process information 

AUTHORS 

uptime was written by Larry Greenfield (greenfie@gauss.rutgers.edu) and M ichael K. Johnson 
(j ohnsonm@sunsite.unc.edu). 

SEE ALSO 

ps( 1), top(l), utmp(5), w(l) 


Cohesve Systems 26 January 1993 
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userlist 

useriist—User listing of who's on your system 

SYNOPSIS 

DESCRIPTION 

This program simply gives you a listing of who isconnected to your system. It is used primarily in thesorted listing that 
utilitizes the same method of display for a more uniform output between systems It also made more sense to do it this way 
instead of having jumbled up display listings in sorted finger displays Besides it made more sense to do this than use 

finger. :) 

This program functions with the same types of things in mind that cfingerd does If the user has a .nofinger file, his or her 
username will not be displayed in the user listing. 

Exampleoutput isshown as 

Username Real Name Idletime TTY Remote console username I'm real ... 9d 23:59 0 
(remote.site.com) 

where it would display the user's login name, the user's real name, the user's idle time given in the format "dd hh: mm", the 
tty, and the remote location (or where the user is telnetting from). 

If the username is more than a certain number of characters the program will not search for their information in the passwd 
fi le because it may be too long. Besides, it checks getpwnam, anyway. 

CONTACTING 

If you like this program, have any suggestions on how it could be modified, or have bug reports please write to 

khollis@bitgate.com. 

Your continued public domain support is appreciated! Thanks. 

SEE ALSO 

cfingerd.conf(5), cfingerd(8), finger(l) 

Userlii 0.0.1,26 August 1995 


UUCP 

uucp— UN IX-to-UNIX copy 

SYNOPSIS 

uucp [ options ] source-file desti nation-fiIe 

uucp [ options ] source-f i I e. ., desti nati on-di rectory 

DESCRIPTION 

The uucp command copies files between systems. Each file argument is either a pathname on the local machine or is of the 
form 

which is interpreted as being on a remote system. In thefirst form, the contents of the first file are copied to the second. In 
thesecond form, each source file is copied into thedestination directory. 
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A file be transferred to or from s y s t e m 2 via s y s t e mi by using 

systeml!system2!path 

Any pathname that does not begin with / or - will be appended to the current directory (unless the -wor --noexpand option 
is used); this resulting path will not necessarily exist on a remote system. A pathname beginning with a simple' starts at the 
uucp public directory; a pathname beginning with 'name starts at the home directory of thenamed user. The' is interpreted 
on the appropriate system. Note that some shells will interpret a simple'to the local home directory before uucp sees it; to 
avoid this, the' must be quoted. 

Shell metacharacters ? * [ ] are interpreted on the appropriate system, assumingthey arequoted to prevent the shell from 
interpreting them first. 

Thecopy does not take place immediately, butisqueued upfortheuucico(8) daemon; thedaemon isstarted immediately 
unless the -r or --nouucico switch is given. In any case, the next time the remote system is called, thefilefs) will be copied. 


OPTIONS 


Thefollowing options may be given to uucp. 


-c, - - nocopy 


-d, - -directories 
-f, - -nodirectories 
-g grade, - -grade grade 



-W, - - noexpand 
-x type, --debug t ype 


-v, - -version 


Do not copy local source files to the spool directory. If they are removed before being 
processed by theuucico(8) daemon, the copy will fail. The files must be readable by the 
uucico(8) daemon, and by the invoking user. 

Copy local source files to the spool directory. Thisisthe default. 

Create all necessary directories when doing the copy. Thisisthedefault. 

If any necessary directories do not exist for the destination path, abort the copy. 

Set the grade of the file transfer command. J obs of a higher grade are executed first. G rades 
run 0 ... 9 a ... z a ... z from high to low. 

Report completion or failure of thefile transfer by maii(l). 

Report completion or failure of the file transfer by maii(l) to the named user on the remote 
system. 

Do not start uucico(8) daemon immediately; merely queue up the file transfer for later 
execution. 

Print j obi d on standard output. The job may be later canceled by passing thej obi d to the 
- k switch of uustat(l). It is possiblefor some complex operations to produce more than 
onej obi d , in which case, each will be printed on a separate line For example, 

uucp sysl !'userl/fi I el s y s 2 ! 'u s e r 2 /f j t e 2 'us er 3 

will generate two separate jobs, one for the system sysi and one for the system s y s 2 . 

Do not prepend remote relative pathnames with thecurrent directory. 

Turn on particular debugging types. Thefollowing types are recognized: abnormal, chat, 
handshake, uucp-proto, proto, port, config, spooldir, execute, incoming, outgoing. 
Only abnormal, config, spooldir, and execute are meaningful for uucp. M ultiple types 
may be given, separated by commas, and the - - debug option may appear multiple times A 
number may also be given, which will turn on that many types from theforegoing list; for 
example, - debug 2 is equivalent to - -debug abnormal,chat. 

Set configuration file to use. Thisoption may not be available depending upon how uucp 
was compiled. 

Report version information and exit. 

Print a help message and exit. 


FILES 

T hefi lenames may be changed at compilation time or by the configuration file, so these are only approximations. 




uuencode 


/usr/lib/uucp/config 

/usr/spool/uucpuucp 

/usr/spool/uucp/Log 

/usr/spool/uucppublic 


Configuration file 
spool directory 
uucp log file 

Default uucp public directory 
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SEE ALSO 

mail(l), uux(l), uustat(l), uucico(8) 

BUGS 

Some of the options are dependent on the capabilities of the uucicof8) daemon on the remote system. 

The -n and -m switches do not work when transferring a file from one remote system to another. 

File modes are not preserved, except for theexecute bit. T he resulting file is owned by the uucp user. 

AUTHOR 

Ian Lance Taylor (ian@airs.com) 

Taylor UUCP 1.05 


uuencode 

uuencode— Encode a binary file 
uudecode—Decodeafilecreated by uuencode 

SYNOPSIS 

uuencode [ -m] [file ] name 
uudecode [-0 outfile] [ file ]... 

DESCRIPTION 

uuencode and uudecode are used to transmit binary files over transmission mediums that do not support other than simple 
ASCII data. 

uuencode reads f i i e (or by default the standard input) and writes an encoded version to the standard output. The encoding 
uses only printing ASC11 characters and includes the mode of thefile and the operand n a me for use by uudecode. If n a me is / 
dev/stdout, the result will be written to standard output. By default, the standard uu encoding format will be used. If the 
option -m isgiven on thecommand line base64 encoding is used instead. 

uudecode transforms uuencoded files (or by default, the standard input) into the original form. The resulting file is named 
name (or outfile if the -0 option isgiven) and will havethe mode of the original file except that setuid and execute bits 
are not retained. If outfile or name is/dev/stdout, the result will be written to standard output, uudecode ignores any 
leading and trailing lines. The program can automatically decide which of the supported encoding schemes are used. 

EXAMPLES 

Thefollowing example packages up a source tree, compresses it, uuencodesit, and mailsittoauseron another system. 
When uudecode isrun on thetargd system, thefile src_tree. tar. z will be created, which may then be uncompressed and 
extracted into theoriginal tree. 

tar cf - src_tree | compress | uuencode src_tree.tar.Z | mail sysl!sys2!user 
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SEE ALSO 

compress(l), mail(l), uucp(l), uuencode(5) 

STANDARDS 

This implementation iscompliantwith P1003.2b/Dll. 

BUGS 

If more than onefile is given to uudecodeand the -o option isgiven or more than one name in the encoded files is the same, 
the result is probably not what is expected. 

The encoded form of the file isexpanded by 37 percent for uu encoding and by 35 percent for base64 encoding (3 bytes 
become4 plus control information). 

HISTORY 

Theuuencode command appeared in BSD 4.0. 

uustat 

uustat— uucp status inquiry and control 

SYNOPSIS 

uustat -a 
uustat --all 

uustat [ -eKRiMNQ ][-sS system ] [ -uU user ] [ -cC command ] [ -oy hours ] 

[ -B lines ] [ --executions ][--kill-all ][--rejuvenate-all [[--prompt [[--mail ] 

[--notify ][--no-list [[--system system ] [ --not-system system ] [ --user user ] 

[--not-user user ] [ --command command ] [ --not-command command ] 

[ --older-than hours ] [ --younger-than hours ] [ --mail-lines I i nes ] 
uustat [ -kr jobid ] [ --kill jobid ] [ --rejuvenate jobid ] 

uustat -q [ -sS system ] [ -oy hours ] [ --system system ] [ --not-system system ] 

[--older-than hours ] [ --younger-than hours ] 

uustat --list [ -sS system ] [ -oy hours ] [ --system system ] 

[ --not-system syst em ] [ --older-than hours ] [ --younger-than hours ] 

uustat -m 
uustat --status 
uustat -p 
uustat --ps 

DESCRIPTION 

The uustat command can display various types of status information about the UUCP system. It can also be used to cancel 
or rejuvenate requests made by uucp(l) or uux(l). 

By default uustat displays all jobs queued up for the invoking user, as if given the --user option with the appropriate 
argument. 







If any of the-a, --all, -e, --executions, -s, --system, -S,--not-system, -u, --user, -U, --not-user, -c, --command, -C, 
--not-command, -o, --oider-than, -y, --younger-than options are given, then all jobs that match the combined specifica¬ 
tions are displayed. 

The -k or --kin-aii option may be used to kill off a selected group of jobs, such as all jobs more than seven days old. 


OPTIONS 


Thefollowing options may be given to uustat. 


t -command command 


- - kill j obi d 


- -rejuvenate j obi d 


List all queued file transfer requests. 

List queued execution requests rather than queued file transfer requests Q ueued execution 
requests are processed by uuxqt(8) rather than uucico(8). Queued execution requests may 
be waiting for some file to be transferred from a remote system. T hey are created by an 
invocation of uux(l). 

List all jobs queued up for the named system. These options may be specified multiple 
times in which case all jobs for all thesystemswill be listed. If used with --list, only the 
systems named will belisted. 

List all jobs queued for systems other than the one named. These options 
may be specified multipletimes, in which case no jobs from any of the specified systems will 
belisted. If used with -- list, only the systems not named will belisted. Theseoptions 
may not be used with -sor - -system. 

List all jobs queued up for the named user. These options may be specified multipletimes, 
in which case all jobs for all the users will belisted. 

List all jobs queued up for users other than the one named. T hese options may be specified 
multipletimes, in which case no jobs from any of the specified users will belisted. These 
options may not be used with -uor --user. 

List all jobs requesting the execution of the named command. If command isALLthiswill 
list all jobs requesting the execution of some command (asopposed to simply requesting a 
file transfer). These options may be specified multipletimes, in which case all jobs 
requesting any of the commands will belisted. 

List all jobs requesting execution of some command other than the named 
command, or, if command is all, list all jobsthat si mply request a file transfer (asopposed 
to requesting theexecution of some command). Theseoptions may be specified multiple 
times, in which case no job requesting one of the specified commands will be listed. T hese 
options may not be used with - c or - - command. 

List all queued jobs older than the given number of hours. If used with --list, only 
systems whose oldest jobholder than the given number of hours will belisted. 

List all queued jobs younger than the given number of hours. If used with --list, 
only systems whose oldest job is younger than the given number of hours will be 
listed. 

Kill the named job. The job ID isshown by the default output format, as well as by the -j 
or --jobid option to uucp(l) or uux(l). A job may only be killed by the user who created 
the job, or by the UUCP administrator or the superuser. The -k or - - km options may be 
used multiple times on the command line to kill several jobs. 

Rq'uvenate the named job. Thiswill mark it as having been invoked atthecurrent 
time, affecting the output Of the -o, -- older-than, -y, or -- younger-than options and 
preserving itfrom any automated cleanup daemon. The job ID isshown by the default 
output format, as well as by the - j or - -jobid options to uucp(l) or uu(l). A job may only 
be rquvenated by the user who created the job, or by the U U C P administrator or the 
superuser. The -r or --rejuvenate optionsmay be used multiple times on thecommand 
lineto rguven ate several jobs 



Parti: User Commands 


568 


-P, --ps 
-i, - - prompt 

-K, - - kill-all 

-R, --rejuvenate-all 
-M f - - mail 


-N, - -notify 


-Q, - -no-list 
-x type, --debug t ype 


-v, - -version 
- -help 


D isplay the status of commands, executions, and conversations for al I remote systems for 
which commands or executions are queued. The-s, --system, -s, --not-system, -o, -- 
older - than, - y, and - - younger - than options may be used to restrict the systems that are 
listed. Systemsfor which no commands or executions are queued will never be listed. 

D isplay the status of conversations for all remote systems. 

D isplay the status of all processes holding uucp locks on systems or ports. 

For each listed job, prompt whether to kill the job or not. If thefirst character of the input 
lineisy ory, the job will be killed. 

Automatically kill each listed job. Thiscan be useful for automatic cleanup scripts, in 

conjunction with the - -man and - -notify options 

Automatically rquvenateeach listed job. This may not be used with --kiii-aii. 

For each listed job, send mail to theUUCP administrator. If the job is killed (due to -- 
kiii-aii or - -prompt with an affirmative response), the mail will indicate that. A comment 
specified by the --comment option may be included. If the job is an execution, the initial 
portion of its standard input will beincluded in the mail message; the number oflinesto 
include may be set with the --mail-lines option (the default is 100). I f the standard input 
contains null characters itisassumed to be a binary file and is not included. 

For each listed job, send mail to the user who requested the job. The mail is identical to that 
sent by the - m or - - man options 

Specify a comment to beincluded in mail sent with the -m, - -man, -n, or - -notify 
options 

Do not actually list the job, butonly take any actions indicated by the-i, --prompt, -k, -- 
kill-all, -M, - -mail, -N, Or --notify Options. 

Turn on particular debugging types. Thefollowing types are recognized: abnormal, chat, 
handshake, uucp-proto, proto, port, config, spooldir, execute, incoming, outgoing. 
Only abnormal, config, spooldir, and execute are meaningful for uustat. 

M ultiple types may be given, separated by commas and the - -debug option may appear 
multiple times A number may also be given, which will turn on that many types from the 
foregoing list; for example, - -debug 2 isequivalent to - -debug abnormal,chat, 
set configuration file to use This option may not be available depending upon how uustat 
was compiled. 

Report version information and exit. 

Print a help message and exit. 


EXAMPLES 

uustat -aii Display status of all jobs. A sampleoutput lineisasfollows: 

bugsA027h bugs ian 04-01 13:50 Executing rmail ian@airs.com (sending 1283 

The format is 

jobid system user queue-date command (size) 

T he j obid may be passed to the - - km or - - re j uvenate options T he size indicates how 
much dataisto be transferred to the remote system, and is absent for a file receive request. 

The--system, --not-system, --user, --not-user, --command, --not-command, --older- 

than.and --younger-than options may be used to control which jobs are listed, 
uustat -executions Display status of queued up execution requests. A sampleoutput lineisasfollows 

bugs bugslian 05-20 12:51 rmail ian 

The format is 

The--system, --not-system, --user, --not-user, --command, --not-command, --older - 

than, and - - younger-than options may beused to control which requests are listed. 



uustat -list Display status for all systems with queued-up commands. A sample output line isasfollows: 

bugs 40 (1 hour) 0X (0 secs) O4-01 14:45 Dial failed 

This indicates the system, the number of queued commands, the age of the oldest queued 
command, the number of queued local executions, the age of the oldest queued execution, 
the date of the last conversation, and the status of that conversation, 
uustat -status D isplay conversation statusfor all remote systems A sampleoutput line isasfollows: 

bugs 04-01 15:51 Conversation complete 

This indicates the system, the date of the last conversation, and thestatus of that conversa¬ 
tion. If the last conversation failed, uustat will indicate how many attempts have been 
made to call the system. If the retry period is currently preventing calls to that system, 
uustat also displays the time when the next call will be permitted, 
uustat -ps D isplay thestatus of all processesholding uucp locks. Theoutputformatissystem- 

dependent, as uustat simply invokes ps(l) on each process holding a lock. A sampleoutput 
lineisas follows 

uustat -command rmail -older-than 168 -kill-all -no-list -mail -notify - 
comment “Queued for over 1 week" 

This will kill all rmati commands that have been queued up waiting for delivery for over 
one week (168 hours). For each such command, mail will be sent both to the UUCP 
administrator and to the user who requested the mail execution. The mail message sent 
will include the string given by the - - comment option. The - - no-list option prevents any 
of the jobs from being listed on the terminal, so any output from the program will be error 
messages 

FILES 

T hefi lenames may be changed at compilation time or by the configuration file, so these are only approximations, 
/usr/iib/uucp/config Configuration file 
/usr/spooi/uucpuucp spool directory 

SEE ALSO 

ps( 1), rmail(l), uuop(l), uux(l), uucico(8), uuxqt(8) 

AUTHOR 

Ian Lance Taylor (ian@airs.com) 

Taylor UUCP 1.05 


UUX 

uux— Remote command execution over uucp 

SYNOPSIS 

uux [ options ] command 

DESCRIPTION 

The uux command is used to execute a command on a remote system, or to execute a command on the local system using 
files from remote systems The command is not executed immediately; the request isqueued until theuucico(8) daemon 
callsthesystem and executesit. Thedaemon isstarted automatically unlessoneof the -r or - -nouucico optionsisgiven. 
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The actual command execution is done by theuuxqt(8) daemon. 

Fileargumentscan be gathered from remote systems to the execution system, as can standard input. Standard output may be 
directed to a file on a remote system. 

The command name may be preceded by a system name followed by an exclamation point if it is to be executed on a remote 
system. An empty system name is taken as the local system. 

Each argument that contains an exclamation point is treated asnamingafile The system thatthefileison is before the 
exclamation point, and the pathnameon that system follows it. An empty system name is taken as the local system; this must 
be used to transfer a file to a command being executed on a remote system. If the path isnot absolute it will be appended to 
the current working directory on the local system; the result may not be meaningful on the remote system. A pathname may 
begin with -/, in which case it is relative to the uucp public directory (usually /usr/spooi/uucppubiic) on the appropriate 
system. A pathname may begin with 'name/, in which case it is relative to the home directory of the named user on the 
appropriate system. 

Standard input and output may be redirected as usual; the pathnames used may contain exclamation points to indicate that 
they are on remote systems N ote that the redi rection characters must be quoted so that they are passed to uux rather than 
interpreted by the shell. Append redirection (») does not work. 

All specified files are gathered together into a single directory before execution of the command begins This means that each 
file must have a distinct base name For example, 

uux 1 sysl!diff sys2!'user1/foo sys3!'user2/foo >!too.diff 1 

will fail because both files will be copied to sysi and stored under the name foo. 

Arguments may be quoted by parentheses to avoid interpretation of exclamation points. This is useful when executing the 
uucp command on a remote system. 


OPTIONS 


Thefollowing options may be given to uux. 


-p, - -stdin 
;, - - nocopy 


-g grade, - -grade grade 

-n, --notification=no 
-z, --notification=er r or 

-r, - -nouucico 


Read standard input and use it as the standard input for the command to be executed. 

Do not copy local files to thespool directory. This is the default. If they are removed before 
being processed by the uucico(8) daemon, thecopy will fai I. T he files must be readable by 
theuucico(8) daemon, as well as by the invoker of uux. 

Copy local files to thespool directory. 

Link local files into thespool directory. If a file can not be linked because it is on a different 
device it will be copied unless one of the -cor --nocopy options also appears (in other 
words, use of --link switches the default from --nocopy to --copy). If thefiles are changed 
before being processed bytheuucico(8) daemon, the changed versions will be used. The 
files must be readable by the uucico(8) daemon, as well as by the invoker of uux. 

Set the grade of the file transfer command. J obs of a higher grade are executed first. G rades 
run 0 ... 9 a ... z a ... z from high to low. 

Do not send mail about the status of the job, even if it fails. 

Send mail about the status of the job if an error occurs For many uuxqt daemons, 
including the T aylor uucp uuxqt, this is the default action; for those - - 
notif ication=e r r o r will have no effect. FI owever, some uuxqt daemons will send mail if 
the job succeeds unless the - - notif ication=emor option is used, and some other uuxqt 
daemons will not send mail if the job fails unless the - -notification=error option is used. 
Do not start theuuoico(8) daemon immediately; merely queue up the execution request for 



--requestor address 
-x type, --debug type 


-I file,- -config file 


-v, - -version 


Print jobids on standard output. A jobid will be generated for each file copy operation 
required to perform the operation. These file copies may be canceled by passing the jobid 
to the - - kin avitch of uustat(l), which will make the execution impossible to complete. 
Report job status to thespecified e-mail address 

Turn on particular debugging types. Thefollowing types are recognized: abnormal, chat, 
handshake, uucp-proto, proto, port, config, spooldir, execute, incoming, outgoing. 
Only abnormal, config, spooldir, and execute are meaningful for u u x . M ultiple types 
may be given, separated by commas, and the - -debug option may appear multiple times A 
number may also be given, which will turn on that many types from theforegoing list; for 
example,--debug 2 is equivalent to --debug abnormal,chat. 

Set configuration file to use This option may not be available depending upon how uux 
was compiled. 

Report version information and exit. 

Print a help message and exit. 


EXAMPLES 

uux -z - sysi! rmaii useri-Execute the command mail useri on the system sysi, giving it asstandard input 
whatever is given to uux as standard input. If a failure occurs send a message using maii(l). 

uux 'diff -c sysi!' useri/filel sys2!'user2/file2 >!file.diffFetch thetWO named files from system sysi and 
system sys2 and executediff, putting the result in file.diff in the current directory. The current directory must be 
writable by the uuxqt(8) daemon forthisto work. 

uux 'sysiiuucp "useri/fiiei (sys2ruser2/fiie2>Executeuuopon thesystem sysi copyingfiiei (on system 
sysi) to sys2. T his illustrates the use of parentheses for quoting. 


RESTRICTIONS 

T he remote system may not permit you to execute certain commands. M any remote systems only permit the execution of 
rmaii and rnews. 

Some of the options are dependent on the capabilities of the uuxqt(8) daemon on the remote system. 


FILES 


The filename may be changed at compilation time or by the configuration file, so these are only approximations. 


/usr/lib/uucp/config 
/usr/spool/uucpuucp 
/usr/spool/uucp/Log 
/usr/spool/uucppublic 


Configuration file 
spool directory 
uucp log file 

D efault uucp public directory 


SEE ALSO 

mail(l), uustat(l), uuop(l), uucico(8), uuxqt(8) 

BUGS 

File can not be referenced across multiple systems 

Too many jobids are output by --jobid, and there is no good way to cancel a local execution requiring remote files 

AUTHOR 

Ian Lance Taylor (ian@airs.com) 
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uuxqt 

uuxqt— uucp execution daemon 

SYNOPSIS 

uuxqt [ opti ons ] 


DESCRIPTION 

The uuxqt daemon executes commands requested by uux(l) from either the local system or from remote systems It is started 
automatically by theuucico(8) daemon (unless uucico(8) isgiven the -qor --nouuxqt option). 

There is normally no need to run this command because it will be invoked byuucico(8). However, it can be used to provide 
greater control over the processing of the work queue. 

M ultiple invocationsof uuxqt may be run at once, as controlled by themax-uuxqts configuration command. 


OPTIONS 


Thefollowing options may be given to uuxqt: 


-c command, - -command command 


-s system, --system system 
-x type, --debug type 


-v, - -version 


0 nly execute requests for the specified command. For example, 

uuxqt -command rmail 

0 nly execute requests originating from the specified system. 

Turn on particular debugging types. Thefollowing types are recognized: abnormal, 
chat, handshake, uucp-proto, proto, port, config, spooldir, execute, incoming, 
outgoing. Only abnormal, config, spooldir and execute are meaningful for 
uuxqt. M ultiple types may be given, separated by commas, and the - -debug option 
may appear multi pie times. A number may also be given, which will turn on that 
many types from the foregoing list; for example - -debug 2 is equivalent to - -debug 
abnormal,chat. 

The debugging output issent to thedebugging file usually /usr/spooi/uucp/ 
Debug, /usr/spool/uucp/DEBUG, Or/usr/spool/uucp/.Admin/audit.local. 

Set configuration file to use This option may not be available depending upon how 
uuxqt was compiled. 

Report version information and exit. 

Print a help message and exit. 


FILES 

T hefi lenames may be changed at compilation time or by the configuration file, so these are only approximations, 
/usr/lib/uucp/config Configuration file 

/usr/spooi/uucpuucp spool directory 

/usr/spool/uucp/Log uucplogfile 


/usr/spool/uucppubiic Default uucp public directory 

/usr/spool/uucp/Debug D ebugging file 


SEE ALSO 

uucp(l), uux(l), uucico(8) 


AUTHOR 

Ian Lance Taylor (ian@airs.com) 


Taylor UUCP 1.05 
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0 

w— Present who users are and what they are doing 

SYNOPSIS 

DESCRIPTION 

T he w utility prints a summary of the current activity on the system, including what each user is doing. The first line displays 
the current time of day, how long the system has been running, the number of users logged into the system, and the load 
averages. The load average numbers give the number of jobs in the run queue averaged over 1, 5, and 15 minutes 
The fields output are the user's login name, the name of the terminal the user ison, the host from which the user islogged 
in, the time the user logged on, the time si nee the user last typed anything, and the name and arguments of the current 
process 

The options are asfollows 

-h Suppress the heading 

-i Output is sorted by idle time 

-n Show network addresses as numbers 

-w Interpret addresses and attempt to display them symbolically 

If a username is specified, the output is restricted to that user. 

FILES 

/var/run/utmp List of users on the system 

SEE ALSO 

who(l), finger(l), ps(l), uptime(l), 

BUGS 

The notion of the current process is muddy. The current algorithm is "the highest numbered process on the terminal that is 
notignoring interrupts, or, if there is none, the highest numbered process on the terminal."Thisfails, for example, in critical 
sections of programs like the shell and editor, or when faulty programs running in the background fork and fail to ignore 
interrupts (In cases where no process can be found, w prints a period.) 

The CPU time is only an estimate; in particular, if someone leaves a background process running after logging out, the 
person currently on that terminal ischarged with thetime 

Background processes are not shown, even though they account for much of the load on the system. 

Sometimes processes, typically those in the background, are printed with null or garbaged arguments In these cases the 
nameof the command is printed in parentheses 

Thew utility does not know about the new conventions for detection of background jobs It will sometimes find aback- 
ground job instead of the right one. 

COMPATIBILITY 

The-f, -l, -s, and -w flags are no longer supported. 

HISTORY 

Thew command appeared in BSD 3.0. 


BSD 4, 6Junel993 
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wall 

wan— W rite a message to users 

SYNOPSIS 

wall [file] 

DESCRIPTION 

wall displays the contents of file or, by default, its standard input, on the terminals of all currently logged in users 
0 nly the superuser can write on the terminals of users who have chosen to deny messages or are using a program that 
automatically denies messages. 

SEE ALSO 

mesg(l), talk(l), write(l), shutdown(8) 

HISTORY 

A wail command appeared in AT&T v7. 

Linux0.99, 8 M arch 1993 


wc 

wc— Print the number of bytes words and lines in files 

SYNOPSIS 

wc |-clw) [--bytes] [--chars] [--lines] [--words] [--help] [--version] [file...] 


DESCRIPTION 

This manual page documents the GN U version ofwc. wc counts the number of bytes, whitespace-separated words, and 
newlines in each given file, or the standard input if none are given or when a file named - isgiven. It prints one line of 
counts for each file, and if thefile was given as an argument, it prints thefilename following thecounts. If more than one 
filename isgiven, wc prints a final linecontaining the cumulative counts, with thefilenametotai. The counts are printed in 
the order lines, words, bytes. 

By default, wc prints all three counts Options can specify that only certain counts be printed. Optionsdo not undo others 
previously given, so wc - - bytes --words prints both the byte counts and the word counts 


OPTIONS 

--version 


Print only the byte counts 
Print only the word counts. 

Print only the newline counts. 

Print a usage message and exit with a non-zero status 
Print version information on standard output, then exit. 


GNU Text Utilities 



whereis 

whereis 

whereis— Locate the binary, source, and manual page files for a command 

SYNOPSIS 
DESCRIPTION 

whereis locates sourcefbinary and manuals sections for specified files The supplied names are first stripped of leading 
pathname components and any (single) trailing extension of the form . ext, for example, .c. Prefixes of s. resulting from use 
of source code control are also dealt with, whereis then attempts to locate the desired program in a list of standard Linux 
places: 
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OPTIONS 

-b Search only for binaries 

-m Search only for manual sections. 

-s Search only for sources. 

-u Search for unusual entries A file is said to be unusual if it does not have one entry of each requested type. Thus 

whereisnn-mnn-unn* asksfor those files in thecurrent directory which have no documentation. 

-B C hange or otherwise limit the places where whereis searches for binaries 

-m Change or otherwise limit the places where whereis searches for manual sections. 

-s C hangeor otherwise limit the places wherewhereissearchesfor sources. 

-f Terminate the last directory list and signals the start of filenames must be used when any of the -b, -m, or -s 

options are used. 

EXAMPLE 

Find all filesin /usr/bin that are not documented in /usr/man/mani with sourcein /usr/src: 
example% cd /usr/bin 

example% whereis -u -M /usr/man/mani -S /usr/src -f * 

FILES 

/{bin,sbin,etc} 

/usr/{lib,bin,old,new,local,games,include,etc,src,man,sbin, 

X386, TeX, g++-include} 

/usr/local/{X386,TeX,XII,include,lib,man,etc,bin,games,emacs} 

SEE ALSO 

chdir(2V) 

BUGS 

Since whereis uses chdir(2V) to run faster, pathnames given with the -m, -s, or -b must be full; that is, they must begin 
with a /. 

8 May 1994 


write 

write- Send a message to another user 

SYNOPSIS 

DESCRIPTION 

write allows you to communicate with other usersby copying lines from your terminal to theirs 
When you run thewrite command, the user you are writing to gets a message of the form: 

Message from yourname@yourhost on yourtty at hh:mm ... 

Any further lines you enter will be copied to the specified user's terminal. If the other user wants to reply, he or she must run 
write as well. 

When you are done, type an end-of-file or interrupt character. The other user will see the message eof, indicating that the 
conversation is over. 





You can prevent people (other than the superuser) from writing to you with themesg(l) command. Some commands, for 
example, nroff(l) and pr(l), may disallow writing automatically, so that your output isn't overwritten. 

If the user you want to write to is logged in on more than oneterminal, you can specify which terminal to write to by 
specifying the terminal name as the second operand to the write command. Alternatively, you can let write select one of 
the terminals— it will pick the one with theshortest idle time Thus, if the user is logged in at work and also dialed up from 
home the message will go to the right place 

The traditional protocol for writing to someone isthat thestring -o, either at the end of a line or on a line by itself, means 
that it's the other person's turn to talk. Thestring oo means that the person believesthe conversation to be over. 

SEE ALSO 

mesg(l), talk(l), who(l) 

HISTORY 

A write command appeared in Version 6 AT&T UN IX. 

12 March 1995 


xllperf 

xi iperf- Xll server performance test program 

SYNTAX 

xllperf [ -option ... ] 

DESCRIPTION 

T he xi i pert program runs one or more performance tests and reports how fast an x server can execute the tests 
M any graphics benchmarks assume that the graphics device is used to display the output of a single fancy graphics applica¬ 
tion, and that the user gets his work done on some other device like a terminal. Such benchmarks usually measure drawing 
speed for lines polygons, text, and so on. 

Because workstations are not used as standalone graphics engines but as super-terminals xi iperf measures window 
management performance as well as traditional graphics performance xiiperf includes benchmarksforthetimeit takes to 
create and map windows (as when you startup an application); to map a preexisting set of windows onto thescreen (as when 
you deiconify an application or pop up a menu); and to rearrange windows (as when you slosh windows to and fro trying to 
find the one you want). 

xi iperf also measures graphics performance for operationsnot normally used in standalone graphics displays, but are 
nonetheless used frequently by x applications. Such operations include copypiane (used to map bitmaps into pixels), 
scrolling (used in text windows), and various stipples and tiles (used for CAD and color halftoning, respectively), 
xiiperf should beused to analyze particular strengths and weaknesses of servers, and is most useful to a server writer who 
wants to analyze and improve a server, xiiperf ismeant to comprehensively exercise just about every Xll operation you can 
perform; it does not purport to be a representative sample of the operations that Xll applications actually use. Although it 
can beused asabenchmark, it was written and is intended as a performance testing tool. 

As such, xiiperf does not whittle down measurements to a single Hexstones or Mexops number. We consider such numbers 
to be uninformative at best and misleading at worst. Some servers that are very fast for certain applications can be very slow 
for others N o single number or small set of numbers is sufficient to characterize how an x implementation will perform on 
all applications However, by knowledge of your favorite application, you may be able to use the numbers xiiperf reports to 
predict its performance on a given x implementation. 
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That said, you might also want to look at xi iperf comp(l), a program to compare the outputs of different xi iperf runs You 
provide a list of files containing results from xi iperf, and it lays them out in a nice tabular format. 

For repeatable results, xi iperf should be run using a local connection on a freshly started server. The default configuration 
runs each test five times in order to see if each trial takes approximately thesame amount of time. Strange glitches should be 
examined; if nonrepeatable, you might chalk them up to daemons and network traffic. Each trial is run for five seconds in 
order to reduce random time differences T he number of objects processed per second isdisplayed to three significant digits, 
but you'll beluckyon mostUNIX systems if the numbers are actually consistent to two digits xiiperf moves the cursor out 
of the test window; you should be careful not to bump the mouse and move it back into the window. (A prize to people who 
correctly explain why!) 

Before running a test, xiiperf determines what the round trip time to the server is, and factors this out of the final timing 
reported. It ensures that the server has actually performed the work requested by fetching a pixel back from the test window, 
which meansthat servers talking to graphics accelerators can't claim that they are done whilein the meantime the accelera¬ 
tor is painting madly. 

By default, xi i perf automatically calibrates the number of repetitions of each test, so that each should take approximately 
the same length of time to run across servers of widely differing speeds However, because each test must be run to comple¬ 
tion at least once some slow servers may take a very long time, particularly on the window moving and resizing tests, and on 
the arc drawing tests 

All timing reports are for the smallest object involved. For example, the line tests use a PoiyLine request to paint several lines 
at once, but report how many lines per second the server can paint, not how many PoiyLine requests per second. Text tests 
paint a line of characters, but report on the number of characters per second. Some window tests map, unmap, or move a 
single parent window, but report on how many children windows per second the server can map, unmap, or move 
The current program is mostly the responsibility of Joel M cCormack. It is based upon thexi iperf developed by Phil 
Karlton, Susan Angebranndt, Chris Kent, M ary Walker, and Todd Newman, who wanted to assess performance differences 
between various servers. Several tests were added in order to write and tunethe PM AX (D ECStation 3100) servers For a 
general release to the world, xiiperf was rewritten to ease making comparisons between widely varying machines, to cover 
most important (and unimportant) x functionality, and to exercise graphics operations in as many different orientations and 
alignments as possible 


OPTIONS 


xiiperf issoldyXlib 
-display host:dpy 




-range 

<t est 1>[ ,<t est 2>] 




-clips default 


based, and accepts the following options: 

Specifies which display to use 

Runs the tests in synchronous mode Normally only useful for debugging xiiperf. 

Runs rectangle tests so that they pack rectangles right next to each other. This makes it easy 
to debug server code for stipples and tiles; if the pattern looks ugly, you've got alignment 
problems 

Repeats each test n times (by default each test is run fivetimes). 

Specifies how long in seconds each test should be run (default 5 seconds). 

Runs all tests This may take a while 

Runs all the tests starting from the specified namet est 1 until thenamet est 2 , tests The 
testnames should be one of the options starting from -dot. For example, -range lineioo 
will perform the tests from the 100 pixel line test, and go on till the last test; -range 
Iine100,dline10 will do the tests from linel 00 to dline10. 

G enerates just the descriptive labels for each test specified. See xi i perf comp for more 
details. 

Specifies the foreground color or pixel value to use 
Specifies the background color or pixel value to use. 

D efault number of clip windows 



xllperf 


579 


rop <rop0 ropl . 
pm <pmO pml . . 




<backing_store_hint> 

-dot 

-recti 

-rectIO 

-rect100 

-rect500 

-srect10 

-srect100 

-srect500 

-osrectl 

-osrect10 

-osrect100 

-osrect500 

-tilerectl 

-tilerect10 

-tilerect100 

-tilerect500 

-oddsrectl 

-oddsrect10 

-oddsrect100 

-oddsrect500 

-oddosrectl 

-oddosrect10 

-oddosrect100 

-oddosrect500 

-oddtilerectl 

-oddtilerect10 


Specifies the color or pixel value to use for drawing the odd segments of a DoubieDashed 
lineor arc. This will default to the bg color. 

Use specified raster ops (default is Gxcopy). This option only affects graphics benchmarks in 
which the graphics function isactually used. 

Use specified planemasks (default is “0). This option only affects graphics benchmarks in 
which theplanemask isactually used. 

U se a visual with <depth> planes per pixel. (Default isthedefault visual.) 

Use a visual with Of dass<vcl ass >. <vc I as s > can beStaticGray, Grayscale, 

StaticColor, Pseudocolor, TrueColor, or DirectColor. (Default isthedefault visual). 

Specify the repetition count. (Default isnumber that takes approximately five seconds.) 
Specify the number of sub windows to use in the Window tests Default is 4,16,25,50,75, 
100, and 200. 

Perform only xii pert version 1.2 tests using version 1.2 semantics 

Perform only xii pert version 1.3 tests using version 1.3 semantics 

Set the save_under window attribute to True on all windows created by xiiperf. Default is 

False. 

set the backing_store window attribute to the given value on all windows created by 
xllperf. <backing_store_hint> Can be WhenMapped Or Always. Default is NotUseful. 

Dot. 

lxl solid-filled rectangle. 

10 x10 solid-filled rectangle. 

100 x100 solid-filled rectangle. 

500x500 solid-filled rectangle. 

lxl transparent stippled rectangle, 8x8 stipple pattern. 

10 x10 transparent stippled rectangle 8x8 stipple pattern. 

100 x100 transparent stippled rectangle, 8x8 stipple pattern. 

500x500 transparent stippled rectangle, 8x8 stipple pattern, 
lxl opaque stippled rectangle, 8x8 stipple pattern. 

10 x10 opaque stippled rectangle 8x8 stipple pattern. 

100 x100 opaque stippled rectangle, 8x8 stipple pattern. 

500x500 opaque stippled rectangle, 8x8 stipple pattern, 
lxl tiled rectangle 4x4 tile pattern. 

10x10 tiled rectangle, 4x4 tile pattern. 

100x100 tiled rectangle 4x4 tile pattern. 

500x500 tiled rectangle 4x4 tile pattern. 

lxl transparent stippled rectangle, 17x15 stipple pattern. 

10x10 transparent stippled rectangle 17x15 stipple pattern. 

100x100 transparent stippled rectangle, 17x15 stipple pattern. 

500x500 transparent stippled rectangle, 17x15 stipple pattern, 
lxl opaque stippled rectangle, 17x15 stipple pattern. 

10x10 opaque stippled rectangle 17x15 stipple pattern. 

100x100 opaque stippled rectangle, 17x15 stipple pattern. 

500x500 opaque stippled rectangle, 17x15 stipple pattern, 
lxl tiled rectangle 17x15 tile pattern. 

10x10 tiled rectangle, 17x15 tilepattern. 
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oddtilerectlOO 

oddtilerect500 

bigsrectl 

bigsrect10 

bigsrect100 

bigsrect500 

bigosrectl 

bigosrect10 

bigosrectl 00 

bigosrect500 

bigtilerectl 

bigtilerect10 

bigtilerect100 

bigtilerect500 

eschertilerectl 

eschertilerect10 

eschertilerectl00 

eschertilerect500 

seg100 

seg500 

seg100c1 

seg100c2 

seg100c3 

dseg10 

dseg100 

ddseg100 

hseg10 

hseg100 

hseg500 

vseglO 

vseg100 

vseg500 

whseg10 

whseg100 

whseg500 

wvseg10 

wvseg100 

wvseg500 



-line100 

-line500 


100x100 tiled rectangle 17x15 tile pattern. 

500x500 tiled rectangle 17x15 tile pattern, 
lxl stippled rectangle 161x145 stipple pattern. 

10x10 stippled rectangle, 161x145 stipple pattern. 

100x100 stippled rectangle 161x145 stipple pattern. 
500x500 stippled rectangle, 161x145 stipple pattern, 
lxl opaque stippled rectangle, 161x145 stipple pattern. 
10x10 opaque stippled rectangle 161x145 stipple pattern. 
100x100 opaque stippled rectangle, 161x145 stipple pattern. 
500x500 opaque stippled rectangle, 161x145 stipple pattern, 
lxl tiled rectangle 161x145 tile pattern. 

10x10 tiled rectangle, 161x145 tile pattern. 

100x100 tiled rectangle 161x145 tile pattern. 

500x500 tiled rectangle 161x145 tile pattern, 
lxl tiled rectangle 215x208 tile pattern. 

10x10 tiled rectangle, 215x208 tile pattern. 

100x100 tiled rectangle 215x208 tile pattern. 

500x500 tiled rectangle 215x208 tile pattern. 

1 -pixel thin line segment. 

10 -pixel thin linesegment. 

100 -pixel thin linesegment. 

500-pixel thin linesegment. 

100 -pixel thin linesegment (1 obscuring rectangle). 

100 -pixel thin linesegment (2 obscuring rectangles). 
100-pixel thin linesegment (3 obscuring rectangles). 

10-pixel thin dashed segment (3 on, 2 off). 

100-pixel thin dashed segment (3 on, 2 off). 

100-pixel thin double-dashed segment (3 fg, 2 bg). 

10 -pixel thin horizontal linesegment. 

100 -pixel thin horizontal linesegment. 

500-pixel thin horizontal linesegment. 

10 -pixel thin vertical linesegment. 

100 -pixel thin vertical linesegment. 

500-pixel thin vertical linesegment. 

10 -pixel wide horizontal linesegment. 

100 -pixel wide horizontal linesegment. 

500-pixel wide horizontal linesegment. 

10 -pixel wide vertical linesegment. 

100 -pixel wide vertical linesegment. 

500-pixel wide vertical linesegment. 

1 -pixel thin (width 0) line. 

10 -pixel thin line. 

100 -pixel thin line 
500-pixel thin line 
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-dline10 

-dlinelBO 

-ddline100 

-wline10 

-wline100 

-wline500 

-wdline100 

-wddline100 

-orect10 

-orect100 

-orect500 

-worect10 

-worect100 

-worect500 

-circlel 

-circle10 

-circle100 

-circle500 

-dcircle100 

-ddcircle100 

-wclrcle10 

-wclrcle100 

-wcircle500 

-wdcircle100 

-wddcircle100 

-pclrcle10 

-pclrcle100 

-wpcircle10 

-wpcircle100 

-fclrcle100 
-fcircle500 
-fcpcircle10 
-fcpcircle100 
-fspcircle10 

-fspcircle100 

-ellipse10 

-ellipse100 

-ellipse500 

-dellipse100 

-ddellipse100 

-wellipse10 


10-pixel thin dashed line(3 on, 2 off). 

100-pixel thin dashed line(3 on, 2 off). 

100-pixel thin double-dashed line(3 fg, 2 bg). 

10 -pixel line, line width % 

100 -pixel line, line width 10. 

500-pixel line, line width 50. 

100-pixel dashed line, line width 10 (30 on, 20 off). 

100-pixel double-dashed line, linewidth 10 (30 fg, 20 bg). 

10 x10 thin rectangle outline. 

100 -pixel thin vertical linesegment. 

500-pixel thin vertical linesegment. 

10 x10 wide rectangle outline 
100 -pixel wide vertical linesegment. 

500-pixel wide vertical linesegment. 

1 -pixel diameter thin (line-width 0) circle. 

10 -pixel diamdter thin circle. 

100 -pixel diameter thin circle. 

500-pixel diameter thin circle. 

100-pixel diameter thin dashed circle (3 on, 2 off). 

100-pixel diameter thin double-dashed circle (3 fg, 2 bg). 

10 -pixel diameter circle linewidth 1. 

100 -pixel diameter circle, linewidth 10. 

500-pixel diameter circle, linewidth 50. 

100-pixel diameter dashed circle linewidth 10 <30 on, 20 off). 

100-pixel diameter doubledashed circle linewidth 10 (30fg, 20 bg). 

10 -pixel diameter thin partial circle, orientation and arc angle evenly distributed. 

100 -pixel diameter thin partial circle 
10 -pixel diameter wide partial circle. 

100 -pixel diameter wide partial circle. 

1 -pixel diameter filled circle. 

10 -pixel diameter filled circle 
100 -pixel diameter filled circle 
500-pixel diameter filled circle 

10 -pixel diameter partial-filled circle chord fill, orientation and arc angle evenly distributed. 
100 -pixel diameter partial-filled circle chord fill. 

10 -pixel diameter partial-filled circle pie slice fill, orientation and arc angleevenly 
distributed. 

100 -pixel diameter partial-filled circle pie slice fill. 

10 -pixel diameter thin (linewidth 0) ellipse, major and minor axissizes evenly distributed. 
100 -pixel diameter thin ellipse. 

500-pixel diameter thin ellipse. 

100-pixel diameter thin dashed ellipse (3 on, 2 off). 

100-pixel diameter thin doubledashed ellipse (3 fg, 2 bg). 

10 -pixel diameter ellipse, linewidth 1. 
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-wellipse100 

-wellipse500 

-wdellipse100 

-wddellipse100 

-pellipse10 

-pellipse100 

-wpellipse10 

-wpellipse100 

-fellipse10 

-fellipse100 

-fellipse500 

-fcpellipse10 

-fcpellipse100 

-fspellipse10 

-fspellipse100 

-triangle10 
■triangle100 

-trap100 

-trap300 

-strap10 

-strap100 

-strap300 

-ostrapl 

-ostrap10 

-ostrap100 

-ostrap300 

-tiletrapl 

-tiletrap10 

-tiletrap100 

-tiletrap300 

-oddstrapl 

-oddstrap10 

-oddstrap100 

-oddstrap300 

-oddostrapl 

-oddostrap10 

-oddostrap100 

-oddostrap300 

-oddtiletrapl 

-oddtiletrap10 


100 -pixel diameter ellipse, line width 10. 

500-pixel diameter ellipse, line width 50. 

100-pixel diameter dashed ellipse, line width 10 (30 on, 20 off). 
100-pixel diameter double-dashed ellipse, line width 10 (30 fg, 20 bg). 
10 -pixel diameter thin partial ellipse. 

100 -pixel diameter thin partial ellipse. 

10 -pixel diameter wide partial ellipse. 

100 -pixel diameter wide partial ellipse 
10 -pixel diameter filled ellipse. 

100 -pixel diameter filled ellipse. 

500-pixel diameter filled ellipse. 

10 -pixel diameter partial-filled ellipse, chord fill. 

100 -pixel diameter partial-filled ellipse, chord fill. 

10 -pixel diameter partial-filled ellipse, pieslicefill. 

100 -pixel diameter partial-filled ellipse, pieslicefill. 

Fill 1-pixel/side triangle 
Fill 10-pixel/side triangle. 

Fill 100-pixel/side triangle. 

Fill lxl trapezoid. 

Fill 10x10 trapezoid. 

Fill 100x100 trapezoid. 

Fill 300x300 trapezoid. 

Fill lxl transparent stippled trapezoid, 8x8 stipple pattern. 

Fill 10x10 transparent stippled trapezoid, 8x8 stipple pattern. 

Fill 100x100 transparent stippled trapezoid, 8x8 stipple pattern. 

Fill 300x300 transparent stippled trapezoid, 8x8 stipple pattern. 

Fill 10x10 opaque stippled trapezoid, 8x8 stipple pattern. 

Fill 10x10 opaque stippled trapezoid, 8x8 stipple pattern. 

Fill 100x100 opaque stippled trapezoid, 8x8 stipple pattern. 

Fill 300x300 opaque stippled trapezoid, 8x8 stipple pattern. 

Fill 10x10 tiled trapezoid, 4x4 tile pattern. 

Fill 10x10 tiled trapezoid, 4x4 tile pattern. 

Fill 100x100 tiled trapezoid, 4x4 tile pattern. 

Fill 300x300 tiled trapezoid, 4x4 tile pattern. 

Fill lxl transparent stippled trapezoid, 17x15 stipple pattern. 

Fill 10x10 transparent stippled trapezoid, 17x15 stipple pattern. 

Fill 100x100 transparent stippled trapezoid, 17x15 stipple pattern. 

Fill 300x300 transparent stippled trapezoid, 17x15 stipple pattern. 

Fill 10x10 opaque stippled trapezoid, 17x15 stipple pattern. 

Fill 10x10 opaque stippled trapezoid, 17x15 stipple pattern. 

Fill 100x100 opaque stippled trapezoid, 17x15 stipple pattern. 

Fill 300x300 opaque stippled trapezoid, 17x15 stipple pat-tern. 

Fill 10x10 tiled trapezoid, 17x15 tile pattern. 

Fill 10x10 tiled trapezoid, 17x15 tile pattern. 
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-oddtiletrap100 

-oddtiletrap300 

-bigstrapl 

-bigstrap10 

-bigstrap100 

-bigstrap300 

-bigostrapl 

-bigostrap10 

-bigostrap100 

-bigostrap300 

-bigtiletrapl 

-bigtiletrap10 

-bigtiletrap100 

-bigtiletrap300 

-eschertiletrapl 

-eschertiletrap10 

-eschertiletrap100 

-eschertiletrap300 

- complex'! 0 
-complex'! 00 
-64poly10convex 

- 64poly100convex 
-64poly10complex 
-64poly100complex 
-ftext 

-f8text 
-f9text 
-f14text16 
-tr10text 
-tr24text 
-polytext 
-polytext16 

-f81text 

-f91text 

-f14itext16 

-f24itext16 

-tr10itext 

-tr24itext 

-scroll10 

-scroll100 

-scroll500 


Fill 100x100 tiled trapezoid, 17x15 tile pattern. 

Fill 300x300 tiled trapezoid, 17x15 tile pattern. 

Fill lxl transparent stippled trapezoid, 161x145 stipple pattern. 

Fill 10x10 transparent stippled trapezoid, 161x145 stipple pattern. 
Fill 100x100 transparent stippled trapezoid, 161x145 stipple pattern. 
Fill 300x300 transparent stippled trapezoid, 161x145 stipple pattern. 
Fill 10x10 opaque stippled trapezoid, 161x145 stipple pattern. 

Fill 10x10 opaque stippled trapezoid, 161x145 stipple pattern. 

Fill 100x100 opaque stippled trapezoid, 161x145 stipple pattern. 

Fill 300x300 opaque stippled trapezoid, 161x145 stipple pattern. 

Fill 10x10 tiled trapezoid, 161x145 tile pattern. 

Fill 10x10 tiled trapezoid, 161x145 tile pattern. 

Fill 100x100 tiled trapezoid, 161x145 tile pattern. 

Fill 300x300 tiled trapezoid, 161x145 tile pattern. 

Fill lxl tiled trapezoid, 216x208 tile pattern. 

Fill 10x10 tiled trapezoid, 216x208 tile pattern. 

Fill 100x100 tiled trapezoid, 216x208 tile pattern. 

Fill 300x300 tiled trapezoid, 216x208 tile pattern. 

Fill 10-pixel/side complex polygon. 

Fill 100-pixel/side complex polygon. 

Fill 10x10 convex 64-gon. 

Fill 100x100 convex 64-gon. 

Fill 10x10 complex 64-gon. 

Fill 100x100 complex 64-gon. 

Character in 80-char line(6x13). 

Character in 70-char line(8x13). 

Character in 60-char line(9x15). 

2-byte character in 40-char line (kl4). 

Character in 80-char line(Times-Roman 10). 

Character in 30-char line (Times-Roman 24). 

Character in 20/40/20 line(6x13, Times-Roman 10,6x13). 

2-byte character in 7/14/7 Iine(kl4, k24). 

Character in 80-char image line (6x13). 

Character in 70-char image line (8x13). 

Character in 60-char image line (9x15). 

2-byte character in 40-char image line (kl4). 

2-byte character in 23-char image line (k24). 

Character in 80-char image line (Times-Roman 10). 

Character in 30-char image line (Times-Roman 24). 

Scroll 10x10 pixels vertically. 

Scroll 100x100 pixels vertically. 

Scroll 500x500 pixels vertically. 
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copywinwinlO 

copywinwin100 

copywinwin500 

copypixwin10 

copypixwin100 

copypixwin500 

copywinpix10 

copywinpix100 

copywinpix500 

copypixpix10 

copypixpix100 

copypixpix500 

copyplane10 

copyplane100 

copyplane500 

putimagelO 

putimage100 

putimage500 

putimagexy10 

putimagexy100 

putimagexy500 

shmputl0 

shmputl00 

shmput500 

shmputxylO 

shmputxy100 

shmputxy500 

getimagelO 

getimage100 

getimage500 

getimagexy10 

getimagexy100 

getimagexy500 

noop 

pointer 

prop 

gc 

create 

ucreate 

unmap 

destroy 

popup 


Copy 10x10 square from window to window. 

Copy 100x100 square from window to window. 

Copy 500x500 square from window to window. 

Copy 10x10 square from pixmapto window. 

Copy 100x100 square from pixmapto window. 

Copy 500x500 square from pixmapto window. 

Copy 10x10 square from window to pixmap. 

Copy 100x100 square from window to pixmap. 

Copy 500x500 square from window to pixmap. 

Copy 10x10 square from pixmap to pixmap. 

Copy 100x100 square from pixmapto pixmap. 

Copy 500x500 square from pixmap to pixmap. 

C opy 10x10 1-bit deep plane 
Copy 100x1001-bit deep plane. 

Copy 500x5001-bit deep plane. 

Putlmage 10x10 square. 

Putlmage 100x100 square. 

Putlmage 500x500 square. 

Putlmage XY format 10x10 square 
Putlmage XY format 100x100 square. 

Putlmage XY format 500x500 square. 

Putlmage 10x10 square, M IT -shared memory extension. 

Putlmage 100x100 square, M IT-shared memory extension. 

Putlmage 500x500 square, M IT-shared memory extension. 
PutlmageXY format 10x10 square, M IT -shared memory extension. 
PutlmageXY format 100x100 square, M IT-shared memory extension. 
PutlmageXY format 500x500 square, M IT-shared memory extension. 
Getl mage 10x10 square 
Getlmage 100x100 square. 

G etl mage 500x500 square. 

Getl mage XY format 10x10 square 
Getl mage XY format 100x100 square. 

Getl mage XY format 500x500 square. 

X protocol NoOperation. 

GetAtomName. 

QueryPointer. 

GetProperty. 

Change graphics context. 

Create child window and map using Mapsubwindows. 

Create unmapped window. 

M ap child window via Mapwindow on parent. 

U nmap child window via unmapwindow on parent. 

Destroy child window via Destroywindow parent. 

H id^expose window via M ap/Unmap pop-up window. 
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M ove window. 

M oved unmapped window. 

M ove window via Movewindowon parent. 

Resize window. 

Resize unmapped window. 

Circulate lowest window to top. 

Circulate unmapped window to top. 

X DEFAULTS 

There are no x defaults used by this program. 

SEE ALSO 

X(l), xbench(l), xllperfcomp(l) 

AUTHORS 

Joel McCormack 
Phil Karlton 
Susan Angebranndt 
ChrisKent 
Keith Packard 
Graeme Gill 

X Version 11 Release 6 

xllperfcomp 

xi iperfcomp- Xll server performance comparison program 

SYNTAX 

xllperfcomp [-rj -ro ] [ -1 label_file ] files 

DESCRIPTION 

The xllperfcomp program merges the output of several xiiperf(l) runs into a nice tabular format. 11 takes the results i n 
each file, fills in any missing test results if necessary, and for each test shows the objectslsecond rate of each server. If invoked 
with the - r or - ro options, it shows the relative performance of each server to the first server. 

N ormally, xi iperfcomp uses the first file specified to determinewhich specific testsit should report on. Some(non-D EC:) 
servers may fail to perform all tests In this case xi iperfcomp automatically substitutes in a rate of 0.0 objectslsecond. Since 
thefirst file determines which tests to report on, thisfile must contain a superset of thetests reported in theother files else 

xi Iperfcomp Will fail. 

You can provide an explicit list of tests to report on by using the ■ 1 switch to specify a file of labels You can create a label file 
by using the -label option in xiiperf. 

OPTIONS 

xi iperfcomp accepts the following options: 

-r Specifiesthat theoutput should also include relative server performance. 

-ro Specifiesthat theoutput should indudeonly relative server performance 

-i_iabei_f lie Specifies a label fileto use. 
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X DEFAULTS 

T here are no x defaults used by this program. 

SEE ALSO 

X(l), xllperf(l) 

AUTHORS 

M ark M oraes wrote the original scripts to compare servers J oel M cCormack just munged them together a bit. 

X Verson 11 Release 6 


xargs 

xargs— Build and execute command lines from standard input 

SYNOPSIS 

xargs [-0prtx] [-e[eof-str]] [-i[replace-str]] [- 1 [max-lines]] [-n max-args] 

[-s max-chars] [-P max-procs] [--null] [--eof[=eof-str]] [--replace[=replace-str]] 
[--max-lines!=max-lines]] [--interactive] [--max-chars=max-chars] [--verbose] 
[--exit] [--max-procs=max-procs] [--max-args=max-args] [--no-run-if-empty] 
[--version] [--help] [command [initial-arguments]] 


DESCRIPTION 

This manual page documents the GN U version of xargs. xargs reads arguments from the standard input, delimited by 
blanks (which can be protected with double or single quotes or a backslash) or newlines, and executes the command (default is 
/bin/echo) oneor more ti mes wi th any initial-arguments followed by arguments read from standard input. Blank lines 
on the standard input are ignored, 
xargs exits with thefollowing status 
0 if it succeeds 

123 if any invocation of the command exited with status 1-125 

124 if the command exited with status 255 

125 if the command is killed by a signal 

126 if the command cannot be run 

127 if the command is not found 
1 if some other error occurred. 


OPTIONS 


- -help 

- -replace[=r e 
-Iffeol ace-st 


Input filenames are terminated by a null character instead of by whitespace, and the quotes 
and backslash are not special (every character istaken literally). D isablestheend-of-file 
string, which istreated like any other argument. Useful when arguments might contain 
whitespace, quote marks, or backslashes TheG N U find -printa option producesinput 
suitable for this mode. 

Set the end-of-file string to eof-str. If the end-of-file string occurs as a line of input, the 
rest of the input is ignored. If eof-str is omitted, there is no end of file string. If this 
option is not given, the end-of-file string defaults to an underscore. 

Printasummary of theoptionsto xargs and exit. 

Replace occurrences of re pi ace - st r in the initial arguments with names read from 
standard input. Also, unquoted blanks do not terminate arguments If replace-str 
is omitted, it defaults to {} (like for find -exec). Implies-x and -1 1. 
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-max-args=max- ar gs, 

-interactive, -p 
-no-run-if-empty, -r 
-max-chars=max-chars 

-verbose, -t 
-version 


Use at most max -1 i nes nonblank input lines per command line; max -1 i n e s defaults to i 
if omitted. Trailing blanks cause an input line to be logically continued on the next input 
line Implies -x. 

Use at most max- a r g s arguments per command line Fewerthan max-args argumentswill 
be used if the size (see the -s option) is exceeded, unless the -x option is given, in which 
case xargs will exit. 

Prompt the user about whether to run each command line and read a line from the 
terminal. Only run the command li ne if the response starts with y or y. Implies -t. 

If the standard input does not contain any nonblanks, do not run the command. N ormally, 
thecommand is run once even if there is no input. 

Use at most max-chars characters per command line including thecommand and initial 
arguments and the terminating nulls at the ends of the argument strings The default is 
as I arge as possi ble, up to 20k characters 

Print the command line on the standard error output before executing it. 

Print the version number of xargs and exit. 

Exit if the size (see the -s option) is exceeded. 

Run up to max-procs processes at a time; the default is i. If max-procs iso, xargs will 
run as many processes as possible at a time. U se the - n option with - p; otherwise, chances 
are that only one exec will be done 


SEE ALSO 

find(lL), locate(lL), iocatedb(5L), updatedb(l) Finding Files (online in info, or printed) 

xauth 

xauth-x authority file utility 

SYNOPSIS 

xauth [ -f a u t h f i I e ][-vqib ][command a r g ... ] 

DESCRIPTION 

The xauth program is used to edit and display the authorization information used in connecting to thex server. This 
program is usually used to extract authorization records from one machine and merge them in on another (as is the case 
when using remote logins or granting access to other users). Commands (described below) may be entered interactively, on 
the xauth command line, or in scripts N ote that this program does not contact the x server. N ormally xauth is not used to 
create the authority file entry in thefirst place; xdm does that. 

OPTIONS 

The following options may be used with xauth. They may be given individually (for example -q -i) or may combined (for 
example, -qi). 

-f authf i i e This option specifies the name of the authority file to use. By default, xauth will usethefile 

specified by thexAUTHORiTY environment variable or xauthority in the user's home 
directory. 

-q This option indicates that xauth should operate quietly and not print unsolicited status 

messages This is the default if an xauth command isgiven on thecommand line or if the 
standard output isnot directed to aterminal. 

-v This option indicates that xauth should operate verbosely and print status messages 

indicating the results of various operations (such as how many records have been read in or 
written out). This is the default if xauth is reading commands from its standard input and 
its standard output isdirected to aterminal. 
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-i Thisoption indicates that xauth should ignore any authority file locks. Normally, xauth 

will refuse to read or edit any authority files that have been locked by other programs 
(usually xdm or another xauth). 

-b Thisoption indicates that xauth should attempt to break any authority file locks before 

proceeding. Use this option only to clean up stale locks. 


COMMANDS 


Thefollowing commands may be used to manipulate authority files: 


[n]extract 
di spl ay name 


[n]list [di 


a y n a me.. . ] 


[n]merge [f i I ename . 


remove di spl ay name. . . 


source fiIename 




An authorization entry for the indicated display using the given protocol and key data is 
added to the authorization file. The data is specified as an even-lengthed string of 
hexadecimal digits each pair representing oneoctet. T hefirst digit of each pairgives 
the most significant 4 bits of the octet, and the second digit of the pair gives the least 
significant 4 bits For example, a 32-character hexkey would represent a 128-bit value. A 
protocol name consisting of just a single period istreated as an abbreviation for 

MIT-MAGIC-COOKIE -1. 

Authorization entries for each of the specified displays are written to theindicated file. If 
the next ract command is used, the entries are written in a numeric format suitable for 
nonbinary transmission (such as secure electronic mail). The extracted entries can be read 
back in using the merge and nmerge commands 

If the filename consists of just a single dash, the entries will be written to the standard 
output. 

Authorization entries for each of the specified displays (or all if no displays are named) are 
printed on the standard output. If the mist command is used, entries will be shown in the 
numeric format used by the nextract command; otherwise, they are shown in a textual 
format. Key data is always displayed in the hexadecimal format given in the description of 
the add command. 

Authorization entries are read from the specified files and are merged into the authorization 
database, superceding any matching existing entries. If the nmerge command is used, the 
numeric format given in the description of the extract command is used. If a filename 
consists of just a single dash, the standard input will be read if it hasn't been read before. 
Authorization entries matching the specified displays are removed from the authority file 
The specified file istreated asa script containing xauth commands to execute. Blank lines 
and lines beginning with a pound sign (#) are ignored. A single hyphen may be used to 
indicate the standard input, if it hasn't already been read. 

Information describing the authorization file, whether or not any changes have been made 
and from where xauth commands are being read is printed on the standard output. 

If any modifications have been made the authority file is written out (if allowed), and the 
program exits. An end-of-file is treated as an implicit exit command. 

The program exits, ignoring any modifications This may also be accomplished by pressing 
the interrupt character. 

A description of all commands that begin with the given string (or all commands if no 
string is given) is printed on the standard output. 

A short list of the valid commands is printed on the standard output. 


DISPLAY NAMES 

Display names for the add, [njextract, [n]iist, [n]merge,and remove commands use thesame format asthemsPLAY 
environment variable and the common -display command-line argument. Display-specific information (such as the screen 
number) is unnecessary and will be ignored. Same-machine connections (such as local-host sockets, shared memory, and the 
Internet Protocol hostname locaihost) are referred to ashostname/unixidispiaynumber so that local entries for different 
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machines may be stored in one authority file. 

EXAMPLE 

The most common use for xauth is to extract the entry for the current display, copy it to another machine, and merge it into 
the user's authority file on the remote machine 




ENVIRONMENT 

This xauth program uses the following environment variables: 

xauthority To get the name of the authority file to use if the -t option isn't used. 

home To get the user's home directory if xauthority isn't defined. 

FILES 

$home/ . xauthority is the default authority file if xauthority isn't defined. 


X Version 11 Release 6 
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[n]merge [fiI enar 


remove displayname... 


source f i I ename 


help [string] 


Authorization entries for each of the specified displays (or all if 
no displaysare named) are printed on thestandard output. If 
the niist command is used, entries will be shown in the 
numeric format used by the nextract command; otherwise 
they are shown in a textual format. Key data is always 
displayed in the hexadecimal format given in the description of 
the add command. 

Authorization entries are read from the specified files and are 
merged into the authorization database, superseding any 
matching existing entries. If the nmerge command is used, the 
numeric format given in the description of the extract 
command is used. I f a filename consists of just a single dash, 
thestandard input will be read if it hasn't been read before 
Authorization entries matching the specified displaysare 
removed from the authority file. 

The specified file is treated as a script containing xauth 
commands to execute. Blank lines and lines beginning with at 
are ignored. A single dash may be used to indicate the standard 
input, if it hasn't already been read. 

I nformation describi ng the authorization file, whether or not 
any changes have been made, and from where xauth com¬ 
mands are being read is printed on thestandard output. 

If any modifications have been made the authority file is 
written out (if allowed), and the program exits. An end of file 
is treated as an implicit exit command. 

The program exits, ignoring any modifications This may also 
be accomplished by pressing the interrupt character. 

A description of all commands that begin with thegiven string 
(or all commands if no string is given) is printed on the 
standard output. 

A shortlist of the valid commands is printed on thestandard 
output. 


DISPLAY NAMES 

Display names for the add, [njextraot, [njiist, [njmerge, and remove commands use the same format asthe display 
environment variable and the common -display command-line argument. Display-specific information (such asthe screen 
number) is unnecessary and will be ignored. Same-machine connections (such as local-host sockets, shared memory, and the 
Internet Protocol hostnamei ocai host) are referred to ashostname/unixidispiaynumber so that local entries for different 
machines may be stored in one authority file. 


EXAMPLE 

The most common use for xauth isto extract the entry for the current display, copy it to another machine and merge it into 
the user's authority file on the remote machine 

% xauth extract 

- $DISPLAY rsh otherhost xauth merge - 
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ENVIRONMENT 

Thisxauth program usesthefollowing environment variables: 

xauthority T o get the name of the authority file to use if the -f option 

isn't used 

home To get the user's home directory if xauthority isn't defined 

FILES 

$home/. xauthority D efauit authority file if xauthority isn't defined 

BUGS 

Users that have unsecured networks should take care to use encrypted file transfer mechanisms to copy authorization entries 
between machines Similarly, theMiT-MAGic-cooKiE-i protocol is not very useful in unsecured environments Sites that are 
interested in additional security may need to use encrypted authorization mechanisms such as Kerberos 
Spaces are currently not allowed i n the protocol name. Q uoting could be added for the truly perverse 

AUTHOR 

Jim Fulton, M IT X Consortium 

X Version 11 Release6 


xbmtopbm 

xbmtopbm- Convert an Xll or X10 bitmap into a portable bitmap 

SYNOPSIS 

xbmtopbm [bi t mapfiI e ] 

DESCRIPTION 

Reads an Xll orXIO bitmap as input. Produces a portable bitmap as output. 

SEE ALSO 

pbmtoxbm(l), pbmtox10bm(l), pbm(5) 

AUTHOR 

Copyright (c) 1988 byjef Poskanzer. 

31 August 1988 


xcmsdb 

xcmsdb- Device Color Characterization utility for X Color M anagement System 

SYNOPSIS 

xcmsdb [ -query ][-remove [[-format 32j16j8 [[filename ] 
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DESCRIPTION 

xcmsdb is used to load, query, or remove device color characterization data stored in properties on the root window of the 
screen as specified in section 7, Device Color Characterization, of the 1C CCM . D evice color characterization data (also 
called the Device Profile) isan integral part of Xlib'sX Color M anagement System (xcms), necessary for proper conversion 
of color specification between device-independent and device-dependent forms, xcms uses 3x3 matrices stored in the 
xdccc_linear_rgb_matrices property to convert color specifications between CIEXYZ and RGB Intensity (XcmsRGBi, also 
referred to as linear RGB), xcms then uses display gamma information stored in the xdccc_linear_rgb_correction property to 
convert color specifications between RGBi and RGB device (XcmsRGB, also referred to as device RGB). 

Note that xcms allows clients to register function sets in addition to its built-in function set for CRT color monitors. 
Additional function sets may store their device profile information in other properties in function set specific format. This 
utility is unaware of these nonstandard properties 

The ASC11 readable contents of filename (or the standard input if no input file is given) are appropriately transformed for 
storage in properties provided the -query or -remove optionsare not specified. 

OPTIONS 

xcmsdb program accepts thefollowing options 
-query 

-format 32j16j8 


SEE ALSO 

xprop(l), Xlib documentation 

ENVIRONMENT 

display To figure out which display and screen to use 

AUTHOR 

C huck Adams, T ektronix, I nc., and Al T abayoyon, SynC hromatics I nc. (added multi visual support) 

X Version 11 Release 6 


Thisoption attempts to readtheXDCCC properties off the 
screen's root window. If successful, it transformsthedata into 
a more readable format, then sends the data to standard out. 
Thisoption attempts to remove the XDCCC propertieson the 
screen's root window. 

Specifies the property format (32,16, or 8 bits per entry) for 
the xdccc_linear_rgb_correction property. Precision of 
encoded floating-point values increases with the increase in 
bits per entry. The default is 32 bits per entry. 


xclock 

xciock—Analog/digital clock for X 

SYNOPSIS 

xclock [ -help ][-analog [[-digital [[-chime ][-hd color ][-hi color ] 

[-update seconds ][-padding number ] 

DESCRIPTION 

The xciock program displays the time in analog or digital form. The time is continuously updated at a frequency which may 
be specified by the user. 
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OPTIONS 


xciock accepts all of the standard X Toolkit command-lineoptionsalong with the additional options listed here: 


-analog 
-digital Or-d 

-hands col or (or-hd col or) 
-highlight color (or -hi color) 

-update seconds 


This option indicates that a brief summary of the allowed 
options should be printed on the standard error. 

This option indicates that a conventional 12-hour clock face 
with tick marks and hands should be used. This is the default. 
Thisoption indicates that a 24-hour digital clock should be 
used. 

Thisoption indicates that the clock should chime once on the 
half hour and twice on the hour. 

Thisoption specifies the color of the handson an analog 
clock. The default is black. 

Thisoption specifies the color of the edges of the hands on an 
analog clock, and isonly useful on color displays The default 
is black. 

Thisoption specifies the frequency in seconds at which xciock 
should update its display. If the clock is obscured and then 
exposed, it will be updated immediately. A value of 30 seconds 
or less will enable a second hand on an analog clock. The 
default is 60 seconds 

Thisoption specifies the width in pixelsof the padding 
between the window border and clock text or picture The 
default is 10 on a digital clock and 8 on an analog clock. 


X DEFAULTS 


This program uses the Clock widget. It understands all ofthecore resource names and classes as well as 


width (class Width) 

height (class Height) 

update (class Interval) 
foreground (class Foreground) 

hands (class Foreground) 

highlight (class Foreground) 

analog (class Boolean) 
chime (class Boolean) 


Specifies the width of the clock. The default for analog clocks 
is 164 pixels the default for digital clocks is whatever is needed 
to hold the clock when displayed in the chosen font. 

Specifies the height of the clock. The default for analog clocks 
is 164 pixels the default for digital clocks is whatever is needed 
to hold the clock when displayed in the chosen font. 

Specifies the frequency in seconds at which the time should be 
redisplayed. 

Specifies the color for the tick marks The default isdepends 
on whether reverseVideo is Specified. If reverseVideo is 
specified, the default isiwhite; otherwise the default is black. 
Specifies the color of the insides of the clock's hands T he 
default depends on whether reverseVideo is specified. If 
reverseVideo isspecified, the default isiwhite; otherwise, the 
default is black. 

Specifies the color used to highlight the clock’s hands. T he 
default depends on whether reverseVideo isspecified. If 
reverseVideo is specified, the default isiwhite; otherwise the 
default is black. 

Specifies whether or not an analog clock should be used 
instead of a digital one. The default isTrue. 

Specifies whether or not a bell should be rung on the hour and 
half hour. 
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padding (class Margin) Specifies the amount of internal paddingin pixelsto beused. 

The default is8. 

font (class Font) Specifies the font to beused for the digital clock. N otethat 

variable width fonts currently will not always display correctly. 


WIDGETS 

In order to specify resources, it is useful to know the hierarchy of the widgets which compose xciock. In the following 
notation, indentation indicates hierarchical structure. The widget class name isgiven first, followed by the widget instance 
name 

XClock xciock 
Clock clock 

ENVIRONMENT 

display To get the default host and display number 

xenvironment T o get the name of a resource file that overrides the global 

resources stored in the resource_manager property 

FILES 

<xRoott/iib/xi i /app-defauits/xciock Specifies required resources 

SEE ALSO 

x(l), xrdb(l), time(3C) 

BUGS 

xciock believes the system clock. 

When in digital mode, the string should be centered automatically. 

AUTHORS 

Tony Della Fera (M IT-Athena, DEC), DaveM ankins(M IT-Athena, BBN),and Ed M oy (UC Berkeley) 

X Version 11 Release 6 


xclipboard 

xclipboard— X clipboard client 

SYNOPSIS 

xclipboard [ -toolkitoption ... ] [ -w ][-nw ] 

DESCRIPTION 

The xclipboard program is used to collect and display text selections that are sent to the Clipboard by other clients. It is 
typically used to saveClipboard selectionsfor later use. It stores each Clipboard selection as a separate string, each of which 
can be selected. Each time Clipboard is asserted by another application, xclipboard transfers the contents of that selection to 
a new buffer and displays it in the text window. Buffers are never automatically deleted, so you'll want to use the delete 
button to get rid of useless items 

Since xclipboard uses a Text W idget to display the contents of the clipboard, text sent to the Clipboard may be reselected for 
usein other applications, xclipboard also responds to requestsfortheClipboard selection from other clients by sending the 
entire contents of the currently displayed buffer. 
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An xciipboard window has the following buttons across the top: 

quit When this button ispressed, xciipboard exits. 

delete When this button ispressed, thecurrent buffer is deleted and 

the next one displayed. 

new Creates a new buffer with no contents Useful in constructing 

a new Clipboard selection by hand. 

save D isplaysa File Save dialog box. Pressing the Accept button 

saves the currently displayed buffer to the file specified in the 
text field. 

next D isplaysthe next buffer in the list. 

previous D isplaysthe previous buffer. 


OPTIONS 

The xciipboard program accepts all of the standard X Toolkit command-line optionsas well as the following: 

-w This option indicates that lines of text that are too long to be 

displayed on onelinein thedipboard should wrap around to 
the following lines 

-nw Thisoption indicatesthat long lines of text should notwrap 

around. This is the default behavior. 


WIDGETS 

In order to specify resources, it is useful to know the hierarchy of the widgets which compose xciipboard. In the following 
notation, indentation indicates hierarchical structure. The widget class name is given first, followed by the widget instance 
name 

xciipboard xciipboard 

Form form 

Command Quit 
Command delete 
Command new 
Command Save 
Command next 
Command prev 
Label index 
Text text 

TransientShell fileDialogShell 
Dialog fileDialog 
Label label 
Command accept 
Command cancel 
Text value 

TransientShell failDialogShell 
Dialog failDialog 
Label label 
Command continue 


SENDING/RETRIEVING CLIPBOARD CONTENTS 

T ext is copied to the Clipboard whenever a client asserts ownership of the Clipboard selection. T ext is copied from the 
Clipboard whenever a client requests the contents of the Clipboard selection. Examples of event bi ndi ngs that a user may 
wish to includein a resource configuration file to use the Clipboard are 
*VT100.Translations: #override \ 

<Btn3Up>: select-end(CLIPBOARD) \n\ 
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<Btn2Up>: insert-selection(PRIMARY,CLIPBOARD) \n\ 

<Btn2Down>: ignore () 

SEE ALSO 

x(l), xcutsei(l), xterm(l), individual client documentation for how to make a selection and send it to the Clipboard. 

ENVIRONMENT 

display To get the default host and display number 

xenvironment T o get the name of a resource file that overrides the global 

resources stored in the resource_manager property 

FILES 

<xRoot>/iib/xn /app-defaults/xciipboard Specifies required resources 

AUTHOR 

Ralph R. Swick (D EC/M IT Project Athena), Chris D. Peterson (M IT X Consortium), Keith Packard (M IT X Consortium) 

X Version 11 Release 6 


xconsole 

xconsole— M onitor system console messages with X 

SYNOPSIS 

xconsole [-tool ki t opt i on ...] [-file f i I e-name ] [-notify] [-stripNonprint] [-daemon] [-verbose] 
[-exitOnFail] 


DESCRIPTION 

The xconsole program displays messages that are usually sent to /dev/consoie. 


OPTIONS 


xconsole accepts all of the standard X Toolkit command-line options along with the additional options listed here 


-file file-name 


-notify, -nonotify 


-daemon 

-verbose 


To monitor some other device, use this option to specify the 
device name. T his does not work on regular files as they are 
always ready to be read from. 

W hen new data are received from the console and the notify 
option is sdt, the icon name of the application has* appended, 
so that it isevidenteven when the application isiconified. - 
notify is the default. 

This option causes xconsole to place itself in the background, 
Using fork/exit. 

When set, thisoption directs xconsole to display an informa- 
ti ve m essage in the first line of the text buffer. 

When set, thisoption directs xconsole to exit when it is unable 
to redirect the console output. 


X DEFAULTS 

This program uses the Athena Text widget, look in the Athena W idget Set documentation for controlling it. 
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WIDGETS 

In order to specify resources, it is useful to know the hierarchy of the widgets that compose xconsoie. In the following 
notation, indentation indicates hierarchical structure. The widget class name isgiven first, followed by the widget instance 
name 

XConsole xconsoie 
XConsole text 

ENVIRONMENT 

display To get the default host and display number. 

xenvironment T o get the name of a resource file that overrides the global 

resources stored in the resource_manager property. 

FILES 

<xRoot>/nb/xi i /app -defaults/xconsoie Specifies required resources 

SEE ALSO 

x(l), xrdb(l), Athena Text widgdt 

AUTHOR 

Keith Packard (M IT X Consortium) 

X Version 11 Release 6 


xcutsel 

xcutsei— Interchange between cut buffer and selection 

SYNOPSIS 

xcutsel [ -tool ki topti on ...] [-selection sel ecti on ] [-cutbuffer number ] 

DESCRIPTION 

The xcutsei program is used to copy the current selection into a cut buffer and to make a selection that containsthe current 
contents of the cut buffer. It acts as a bridge between applications that don't support selections and those that do. 

Bydefault, xcutsei will use the selection named primary and the cut buffer cut_buffer 0 . Either or both of these can be 
overridden by command-line arguments or by resources 
An xcutsei window hasthefollowing buttons 

quit When this button is pressed, xcutsei exits. Any selections held 

by xcutsei are automatically released. 

copy primary to 0 When thisbutton ispressed, xcutsei copiesthecurrent 

selection into the cut buffer. 

copy 0 to primary When thisbutton ispressed, xcutsei convertsthecurrent 

contents of the cut buffer into the selection. 

The button labels reflect the selection and cut buffer selected by command-line options or through the resource database 
When thecopy Oto PRIMARY button is activated, the button will remain inverted as long as xcutsei remainstheowner of 
theselection. Thisservesto remind you which client owns the current selection. Note that the value of the selection remains 
constant; if the cut buffer is changed, you must again activate the copy button to retrieve the new value when desired. 
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OPTIONS 

xcutsei accepts all of the standard X Toolkit command-line options as well asthefollowing: 

-selection name T his option specifies the name of the selection to use The 

default is primary. T he only supported abbreviations for this 
option are - select, -sei, and -s, as the standard toolkit option 
-seiectionTimeout hasa similar name. 

-cutbutfer number Thisoption specifies the cut buffer to use. Thedefault is 

cutbuffer 0. 


X DEFAULTS 

This program accepts all of the standard X Toolkit resource names and classes as well asthefollowing: 
selection (class selection) Thisresourcespecifiesthenameof theselection to use. The 

default is primary. 

cutBufter (class cutBuffer) This resource specifies the number of the cutbuffer to use. 

Thedefault is 0 . 


WIDGET NAMES 

Thefollowing instance names may be used when user configuration of the labels in them isdesired: 
sel-cut (class Command) ThisiSthe"COpy SELECTIONtO BUFFER" button, 

cut-sel (class Command) ThisiSthe"COpy BUFFERtO SELECTION" button, 

quit (class command) Thisisthe"quit" button. 

SEE ALSO 

x(l), xciipboard(l), xterm(l), text widget documentation, individual client documentation for how to make a selection. 

BUGS 

T here is no way to change the name of the selection or the number of the cut buffer while the program is running. 

AUTHOR 

Ralph R. Swick (D EC/M IT Project Athena) 

X Version 11 Release 6 


xdm 

xdm- X D isplay M anager with support for XD M C P, host chooser 

SYNOPSIS 

xdm [ -config confi gurati onfi I e ][-nodaemon ] [-debug debugjevel ] 

[-error error_l og_f i I e ][-resources resourc e_ f i I e [[-server serverentry ] 

[-sessi onsessi on_program] 

DESCRIPTION 

xdm manages a collection ofX displays, which may be on the local host or remote servers. The design of xdm was guided by 
the needs of X terminals as well astheX Consortium standard xdmcp, theX Display M anagerControl Protocol, xdm provides 
services similar to those provided by imt, getty, and login on character terminals: prompting for login name and password, 
authenticating the user, and running a session. 




Parti: User Commands 


600 


A session isdefined by the lifetime of a particular process; in the traditional character-based terminal world, it is the user's 
login shell. In the xdm context, it is an arbitrary session manager. This is because in a windowing environment, a user's login 
shell process does not necessarily have any terminal-like interface with which to connect. When areal session manager isnot 
available, a window manager or terminal emulator is typically used asthesess'on manager, meaning that termination of this 
process terminates the user's session. 

When the session isterminated, xdm resets theX server and (optionally) restarts the whole process. 

When xdm receivesan Indirect query via XDM CP, it can run a chooser process to perform an XDM CP BroadcastQuery (or 
an XDM CP Query to specified hosts) on behalf of the display and offer a menu of possible hosts that offer XDM CP display 
management. This feature is useful with X terminals that do not offer a host menu themselves 

Because xdm provides the first interface that users will see, it isdesigned to be simple to use and easy to customize to the needs 
of a particular site, xdm has many options most of which have reasonable defaults. Browse through the various sections of this 
manual, picking and choosing the things you want to change. Pay particular attention to the "Session Program" subsection, 
which will describe how to set up the style of session desired. 

OVERVIEW 

xdm is highly configurable, and most of its behavior can be controlled by resource files and shell scripts. The names of these 
files themselves are resources read from the file xdm-config or thefile named bythe-config option, 
xdm offersdisplay management two different ways It can manageX servers running on thelocal machine and specified in 
xservers, and it can manage remote X servers (typicallyX terminals) using xdmcp (theXD M Control Protocol) asspecified in 
thexaccess file 

T he resources of the X clients run by xdm outside the user's session, including xdm'sown login window, can be affected by 
setting resources in thexresources file. 

For X terminals that do not offer a menu of hosts to gdt display management from, xdm can collect willing hosts and run the 
chooser program to offer the user a menu. ForX displays attached to a host, this step is typically not used, as the local host 
does the display management. 

After resetting the X server, xdm runs the xsetup script to assist in setting up the screen the user sees along with thexiogin 
widget. 

When the user logsin, xdm runs the xstartup script as root. 

Then xdm runs the xsession script as the user. This system session file may do some additional startup and typically runs a 
script in the user's home directory. When the xsession script exits, the session isover. 

At the end of the session, thexreset script is run to clean up, theX server is reset, and the cycle starts over. 

Thefile /usr/xiiR6/iib/xii/xdm/xdm-errons will contain error messages from xdm and anything output to stderr by xsetup, 
xstartup, xsession, orxreset. When you have trouble getting xdm working, check this file to see if xdm has any clues to the 
trouble. 

OPTIONS 

All of these options, except -contig itself, specify values that can also be specified in the configuration file as resources. 

-contig conf i gur at i on.f i i e N ames the configuration file, which specifies resources to 

control the behavior Of xdm. <XRoot>/lib/X11/xdm/xdm-config is 
the default. See the subsection called "Configuration File." 

-nodaemon Specifies false as the value for the DisplayManager.daemonMode 

resource. This suppresses the normal daemon behavior, which 
is for xdm to close all file descriptors, disassociate itself from the 
controlling terminal, and put itself in the background when it 
first starts up. 
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-debug debug_level 




-udpPort por t _ number 


Specifies the numeric value for the DisplayManager.debugLevel 
resource. A non-zero value causes xdm to print lots of 
debugging statements to the terminal; it also disables the 
DisplayManager.daemonModeresource, forcing xdm to run 
synchronously. To interpret these debugging messages, a copy 
of the source code for xdm is almost a necessity. N o attempt has 
been made to rationalize or standardize the output. 

Specifies the value for the DisplayManager. errorLogFile 
resource. This file contains errors from xdm as well as anything 
written to stderr by the various scripts and programs run 
during the progress of the session. 

Specifies the valuefor the DispiayManager*resources resource 
Thisfile is loaded using xrdb to specify configuration 
parametersfortheauthentication widget. 

Specifies the value for the DispiayManage r. servers resource 
See the subsection "Local Server Specification" for a descrip¬ 
tion of this resource 

Specifies the valuefor the DisplayManager. requestPort 
resource. This sets the port number, which xdm will monitor 
for XDM CP requests AsXDMCP uses the registered well- 
known UDP port 177, this resource should not be changed 
except for debugging. 

Specifies the value for the DispiayManager*session resource 
This indicates the program to run as the session after the user 
has logged in. 

Allows an arbitrary resource to be specified, as in most X 
T oolkit applications 


RESOURCES 

At many stages the actions of xdm can be controlled through the use of its configuration file, which is in theX resource 
format. Some resources modify the behavior of xdm on all displays, while others modify its behavior on a single display. 

W here actions relate to a specific display, the display name is i nserted into the resource name between Display-Manager and 
the final resource name segment. 

For local displays, the resource name and class are as read from thexservers file. 

Forremotedisplays, the resource name is what the network address of thedisplay resolvesto. Seethe removeDomain resource 
The name must match exactly; xdm is not aware of all the network aliases that might reach a given display. If the name resolve 
fails, the address is used. T he resource class is as sent by the display i n the X D M C P M anage request. 

Because the resource manager uses colons to separate the name of the resource from its value and dots to separate resource 
name parts, xdm substitutes underscores for both dots and colons when generating the resource name. For example 
DispiayManage r. expo x org 0 . startup is the name of the resource that defi nes the startup shell file for the expo. x. org : 0 
display. 

DisplayManager. servers This resource either specifiesa filename full of server entries, 

one per line (if the value starts with a slash), or a single server 
entry. See the subsection "Local Server Specification" for the 
details. 

DisplayManager. requestPort This indicates the U D P port number that xdm usesto listen for 

incoming XDM CP requests. Unless you need to debug the 
system, leave this with its default value of 177 . 
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DisplayManager.errorLogFile 


DisplayManager.debugLevel 


DisplayManager.daemonMode 


DisplayManager.pidFile 


DisplayManager.lockPidFile 


DisplayManager.authDir 
DisplayManager.autoRescan 


DisplayManager.removeDomainname 


DisplayManager.keyFile 


Error output isnormally directed at the system console. T o 
redirect it, set this resource to afilename. A method to send 
these messages to sysiog should be developed for systems that 
support it; however, the wide variety of interfaces precludes 
any system-independent implementation. Thisfile also 
contains any output directed to stderr by the xsetup, xstartup, 
xsession, and xreset files, so it will contain descriptions of 
problemsin those scripts as well. 

If the integer value of this resource is greater than zero, reams 
of debugging information will be printed. It also disables 
daemon mode, which would redirect the information into the 
bit-bucket, and allows nonroot users to run xdm, which would 
normally not be useful. 

N ormally, xdm attempts to make itself i nto a daemon process 
unassociated with any terminal. This is accomplished by 
forking and leaving the parent process to exit, then closing file 
descriptors and releasing the controlling terminal. In some 
environments this is not desired (in particular, when 
debugging). Setting this resource to false will disablethis 
feature. 

Thefilenamespecified will be created to contain an ASCII 
representation of the process-id of the main xdm process xdm 
also uses file locking on thisfile to attempt to eliminate 
multiple daemons running on the same machine which would 
cause quite a bit of havoc. 

This isthe resource which controls whether xdm uses file 
locking to keep multiple display managers from running 
amok. On System V, this uses the lockf library call, while on 
BSD itusesfiock. 

This names a directory in which xdm stores authorization files 
while initializing the session. T he default value is y. 

This Boolean controls whether xdm rescans the configuration, 
servers, access control and authentication keys files after a 
session terminates and the files have changed. By default it is 
true. You can force xdm to reread these files by sending a 
sighup to the main process. 

When computing the display name for xdmcp clients, the name 
resolver will typically create a fully qualified hostname for the 
terminal. As this is sometimes confusing, xdm will remove the 
domain name portion of the hostname if it is the same as the 
domain name of the local host when this variable is set. By 
default the value istrue. 

xdm-authentication- i styleXDMCP authentication requires 
that a private key be shared between xdm and the terminal. This 
resource specifies the file containing those values Each entry 
in thefile consists of a display name and theshared key. By 
default, xdm does not include support for xdm-authentication- 1 , 
as it requires des, which is not generally distributable because 
of U nited States export restrictions 




DisplayManager.accessFile 


DisplayManager.exportList 


DisplayManage r. randomFile 


DisplayManager.greeterLib 


DisplayManager.choiceTimeout 


DisplayManager.DI SPLAY.resources 


DisplayManager.DI SPLAY.chooser 

DisplayManager.DI SPLAY.xrdb 
DisplayManager.DI SPLAY.cpp 


T o prevent unauthorized XD M C P service and to allow 
forwarding of XDM CP indirectQuery requests, thisfile 
contains a database of hostnames that are either allowed direct 
access to this machine or havea list of hosts to which queries 
should be forwarded to. Theformat of thisfile isdescribed in 
the subsection "XDM CP Access Control." 

A list of additional environment variables, separated by 
whitespace, to pass on to thexsetup, xstartup, xsession.and 
xreset programs 

A file to checksum to generate the seed of authorization keys. 
This should beafilethat changes frequently. Thedefault is 

/dev/mem. 

0 n systems that support a dynamically loadable greater library, 
the name of the library. Default is<XRoot>/iib/xn/xdm/ 
libXdmGreet.so. 

N umber of seconds to wait for display to respond after user 
has selected a host from the chooser. If the display sends an 
XD M C P indirectQuery within thistime the request is 
forwarded to the chosen host. Otherwise, it is assumed to be 
from a new session and the chooser isoffered again. Default 
is 15. 

This resource specifies the name of thefile to be loaded by 
xrdb as the resource database onto the root window of screen 0 
of the display. Thexsetup program, theLogin widget, and 
chooser will use the resources set in thisfile. This resource 
database is loaded just before the authentication procedure is 
started, so it can control the appearance of the login window. 
See the subsection "Authentication Widget," which describes 
the various resources that are appropriate to place in thisfile 
There is no default valuefor this resource, but <xRoot>/iib/ 
xn/xdm/xresources istheconventional name. 

Specifies the program run to offer a host menu for indirect 
queries redirected to thespecial hostname chooser. <xRoot> 

/ nb/xi i /xdm/ chooser is the default. See the subsections 
"XD M CP Access Control" and "chooser." 

Specifies the program used to load the resources. By default, 
xdm Uses<XRoot>/bin/xrdb. 

T his specifies the name of the C preprocessor that is used by 


DisplayManager.DI SPLAY.setup 


DisplayManager.DI SPLAY.startup 


DisplayManager.DI SPLAY.session 


This specifies a program that is run (as root) before offeri ng 
theLogin window. This may be used to change the appearance 
of the screen around theLogin window or to put up other 
windows (for example you may want to run xconsoie here). 

By default, no program isrun. The conventional name for a 
file used hereisxsetup. See the subsection "Setup Program." 
This specifies a program that is run (as root) after the 
authentication process succeeds By default, no program isrun. 
The conventional nameforafileused here is xstartup. Seethe 
subsection "Startup Program." 

Thisspecifiesthesession to be executed (not running as root). 
By default, <xRoot>/bin/xterm isrun. The conventional name 
isxsession. See the subsection "Session Program." 
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DisplayManager.DI SPLAY.reset 


DisplayManager.DI SPLAY.openDelay, 
DisplayManager.DI SPLAY.openRepeat, 
DisplayManager.DI SPLAY.openTimeout, 
DisplayManager.DI SPLAY.startAttempts 


DisplayManager.DI SPLAY.pinglnterval, 
DisplayManager.DI SPLAY. pingTimeout 


DisplayManager.DI SPLAY. 
terminateServer 


DisplayManager.DI SPLAY.userPath 


DisplayManager.DI SPLAY. 
systemPath 


This specifies a program which is run (as root) after the session 
terminates. Again, by default, no program isrun. The 
conventional nameisxreset. See the subsection "Reset 
Program." 

T hese numeric resources control the behavior of xdm when 
attempting to open intransigent servers. openDelay isthe length 
of the pause (in seconds) between successive attempts, 
openRepeat isthe number Of attempts to make openTimeout is 
the amount of time to wait while actually attempting the open 
(that is, the maximum time spent in theconnect(2) system 
call) and startAttempts isthenumber of times thisenti re 
process is done before giving up on the server. After openRepeat 
attempts have been made, or if openTimeout seconds elapse in 
any particular attempt, xdm terminates and restarts the server, 
attempting to connect again. This process is repeated 
startAttempts times, at which point the display isdeclared 
dead and disabled. Although this behavior may seem arbitrary, 
it has been empirically developed and works quite well on 
most systems The default values are 5 for openDelay, 5 for 
openRepeat, 30 for openTimeout and 4 for startAttempts. 

To discover when remote displays disappear, xdm 
occasionally pingsthem, using an X connection and xsync 
calls pinglnterval specifies the time (in minutes) between 
each ping attempt, pingTimeout specifies the maximum 
amount of time (in minutes) to wait for the terminal to 
respond to the request. If the terminal does not respond, the 
session isdeclared dead and terminated. By default, both are 
set to 5 minutes. If you frequently use X terminals that can 
become isolated from the managing host, you might want to 
increase this value. The only worry is that sessions will 
continue to exist after the terminal has been accidentally 
disabled, xdm will not ping local displays Although it would 
seem harmless it is unpleasant when the workstation session is 
terminated as a result of the server hanging for N FS service 
and not responding to the ping. 

This Boolean resource specifies whether the X server should be 
terminated when a session terminates (instead of resetting it). 
This option can be used when the server tends to grow 
without bound overtime, in order to limit the amount of time 
the server isrun. The default value is false, 
xdm sdts the path environment variable for the session to this 
value. It should be a colon separated list of directories; see 
sh(l) forafull description. : /bin:/usr/bln:/usr/X11R6/bin 
:/usr/ucb isacommon setting. The default value can be 
specified at build timein thex system configuration file with 

DefaultUserPath. 

xdm sdtsthePATH environment variable for the startup and reset 
scripts to the value of this resource T he default for this 
resource is specified at build time bytheDefauitsystem-Path 
entry in the system configuration file; /etc:/bin:/usr/bin 



DisplayManager.DI SPLAY. 
systemShell 

DisplayManager.DI SPLAY 
failsafeClient 


DisplayManager.DI SPLAY.grabServer, 
DisplayManager.DI SPLAY. grabTimeout xdm 


DisplayManager.DI SPLAY.authorize, 
DisplayManager.DI SPLAY.authName 


DisplayManager.DI SPLAY.authFile 


DisplayManager.DI SPLAY. 
authComplain 

DisplayManager.DI SPLAY. 
resetSignal 

DisplayManager.DI SPLAY. 
termSignal 


: /usr/xii R6/bin: / usr / ucb is a common choice Note the 
absence of (.) from this entry. Thisisagood practice to follow 
for root; it avoids many common T rojan H orse system 
penetration schemes 

xdm sdts the shell environment variable for the startup and 
reset scriptsto thevalueof thisresource It is /bin/sh by 
default. 

If the default session fails to execute, xdm will fall back to this 
program. This program is executed with no arguments but 
executes using the same environment variables as the session 
would have had. (See the subsection "Session Program.") By 
default, <xRoot>/bin/xterm isused. 

To improve security, this grabs the server and keyboard while 
reading the login name and password. The grabServer resource 
specifies if the server should be held for theduration of the 
nam^password reading. When false, the server is ungrabbed 
after the keyboard grab succeeds; otherwise, the server is 
grabbed until just before the session begins. The default is 
false. The grabTimeout resource specifies the maximum time 
xdm will wait for the grab to succeed. T he grab may fail if some 
other client has the server grabbed, or possibly if the network 
latencies are very high. This resource has a default value of 3 
seconds; you should be cautious when raising it, as a user can 
be spoofed by a look-alike window on the display. If the grab 
fails, xdm kills and restarts the server (if possible) and the 
session. 

authorize isa Boolean resource that controls whether xdm 
generates and uses authorization for the local server connec¬ 
tions. If authorization isused, authName isa list of authorization 
mechanisms to use separated by whitespace XD M C P 
connections dynamically specify which authorization 
mechanisms are supported, so authName is ignored in thiscase. 
W hen authorize is set for a display and authorization is not 
available, the user is informed by having a different message 
displayed in the Login widget. By default, authorize is true. 

authName iSMIT-MAGIC-C00KIE-1, or, if XDM-AUTHORIZATION-1 is 

available, xdm-authorization-i mit-magic-cookie-i . 
Thisfileisused to communicate the authorization data from 
xdm to the server, usingthe-auth server command-line option. 
It should be kept in a directory that is not world-writable as it 
could easily be removed, disabling the authorization mecha¬ 
nism in theserver. 

If set to false, disables the use of the unsecureGreeting in the 
login window. See the subsection "Authentication W idget." 
The default is true. 

The number of the signal xdm sends to reset the server. 

See the subsection "Controlling the Server." The default is i 
(sighup). 

The number of the signal xdm sends to terminate the server. See 
the subsection "Controlling the Server." The default is is 
(sigterm). 
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DisplayManager.DI SPLAY. 
resetForAuth 


DisplayManager.DI SPLAY. 
userAuthDir 


Theoriginal implementation of authorization in the sample 
server reread theauthorization file at server reset time, instead 
of when checking the initial connection. Asxdm generates the 
authorization information just before connecting to the 
display, an old server would not get up-to-date authorization 
information. This resource causes xdm to send sighup to the 
server after setting up the file causing an additional server reset 
to occur, during which time the new authorization information 
will be read. The default is false, which will work for all M IT 
servers. 

When xdm is unable to write to the usual user authorization file 
($home/ .xauthority), it creates a unique filename in this 
directory and points the environment variable xauthority at 
the created file It uses / tmp by default. 


CONFIGURATION FILE 

First, the xdm configuration file should beset up. M ake a directory (usually <xRoot>/nb/xn/xdm, where <XRoot> refers to the 
rootoftheXll install tree) to contain all of the relevant files. In the examples that follow, /usr/xiiR6 is used as the value of 

<XRoot>. 

Here is a reasonable configuration file which could be named xdm-config: 

DisplayManager.servers: /usr/X11R6/lib/X11/xdm/Xservers 
DisplayManager.errorLogFile: /usr/X11R6/lib/X11/xdm/xdm-errors 
DisplayManager*resources: /usr/X11R6/lib/X11/xdm/Xresources 
DisplayManager*startup: /usr/X11R6/lib/X11/xdm/Xstartup 
DisplayManager*session: /usr/X11R6/lib/X11/xdm/Xsession 
DisplayManager.pidFile: /usr/X11R6/lib/X11/xdm/xdm-pid 
DisplayManager. 0.authorize: true 
DisplayManager*authorize: false 

Note that this file mostly contains references to other files Note also that some of the resources are specified with * 
separating the components. These resources can be made unique for each different display, by replacing the* with the 
display name but normally this is not very useful. Seethe "Resources" section for a complete discussion. 

XDMCP ACCESS CONTROL 

The database file specified by the DisplayManager. accessFiie provides information which xdm uses to control access from 
displays requesting XDM CP service This file contains three types of entries: entries that control the response to Direct and 
Broadcast queries, entries that control the response to indirect queries, and macro definitions 
The format of the Direct entries is simple, either a hostname or a pattern, which is distinguished from a hostname by the 
inclusion of one or more metacharacters (* matches any sequence of 0 or more characters and ? matches any single 
character) which are compared against the hostname of the display device. If the entry is a hostname, all comparisons are 
done using network addresses, so any name which converts to the correct network address may be used. For patterns, only 
canonical hostnames are used in the comparison, so ensure that you do not attempt to match aliases. Preceding either a 
hostname or a pattern with a i character causes hosts that match that entry to be excluded. 

An indirect entry also contains a hostname or pattern, but follows it with a list of hostnames or macros to which indirect 
queries should be sent. 

A macro definition contains a macro name and a list of hostnames and other macros that the macro expands to. To 

distinguish macros from hostnames, macro names start with a % character. M acros may be nested. 

indirect entries may also specify to have xdm run chooser to offer a menu of hosts to connect to. See the subsection 

"chooser." 






W hen checking access for a particular display host, each entry isscanned in turn and thefirst matching entry determines the 
response. Direct and Broadcast entries are ignored when scanning for an indirect entry and vice versa. 

Blank lines are ignored, # istreated as a comment delimiter causing the rest of that line to be ignored, andWwiine causes the 
newlineto be ignored, allowing indirect host lists to span multiple lines. H ere is a sample xaccess file 

# Xaccess - XDMCP access control file 


# Direct/Broadcast query entries 

'xtra.lcs.mit.edu # disallow direct/broadcast service for xtra 
bambi.ogi.edu # allow access from this particular display 
.lcs.mit.edu # allow access from any display in LCS 

# Indirect query entries 

%HOSTS expo.lcs.mit.edu xenon.lcs.mit.edu \ 

excess.lcs.mit.edu kanga.lcs.mit.edu extract.lcs.mit.edu xenon.lcs.mit.edu #force extract to contact xenon 
'xtra.lcs.mit.edu dummy #disallow indirect access 
.lcs.mit.edu %HOSTS #all others get to choose 


chooser 

For X terminals that do not offer a host menu for use with Broadcast or indirect queries, the chooser program can do this 
for them. In the xaccess file specify chooser as thefirst entry in the indirect host list, chooser will send a Q uery request to 
each of the remaining hostnames in the list and offer a menu of all the hosts that respond. 

The list may consist of the word broadcast, in which case chooser will send a Broadcast instead, again offering a menu of all 
hosts that respond. Note that on some operating systems, UDP packets cannot be broadcast, so thisfeature will not work. 
Example xaccess file using chooser: 

extract.lcs.mit.edu CHOOSER %HOSTS #offer a menu of these hosts 
xtra.lcs.mit.edu CHOOSER BROADCAST #offer a menu of all hosts 

The program to use for chooser isspecified bytheDispiayManager.Di splay .chooser resource For more flexibility at thisstep, 
the chooser could be a shell script, chooser is the session manager here it is run instead of a child xdmto manage the display. 
Resources for this program can be put into thefilenamed by DispiayManager.Di splay .resources. 

When the user selects a host, chooser prints the host chosen, which isread by the parent xdm, and exits, xdm closes its 
connection to the X server, and the server resets and sends another indirect XDMCP request, xdm remembers the user's 
choice (for DispiayManager. choiceTimeout seconds) and forwards the request to the chosen host, which starts a session on that 
display. 

LOCAL SERVER SPECIFICATION 

The resource DispiayManager. servers gives a server specification or, if the values starts with a slash (/), the name of a file 
containing server specifications, one per line. 

Each specification indicates a display which should constantly be managed and which is not using XDM CP. This method is 
used typically for local servers only. If the resource or thefilenamed by the resource is empty, xdm will offer XDM CP service 
only. 

E ach specification consists of at least three parts: a display name, a display class, a display type, and (for local servers) a 
command line to start the server. A typical entry for local display number 0 would be 

:0 Digital-QV local /usr/XI1R6/bin/X :0 
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The display types are 

Local local display: xdm must run theserver 

Foreign remote display: xdm opens an X connection to a running server 

The display name must be something that can be passed in the -display option to an X program. This string is used to 
generate the display-specific resource names, so be careful to match the names (for example, use: 0 sun-cG3 local /usr 
/xiiR6/bin/x :0 instead of iocaihost:0 Sun-CG3 local /usr/xi i R6/bin/x :0 if your other resources are specified as 
DispiayManager._0. session). The display class portion isalso used in the display-specific resources, as the class of the 
resource. This is useful if you have a large collection of similar displays (such as a corral of X terminals) and would like to set 
resourcesfor groups of them. W hen using XD M C P, the display is required to specify the display class, so the manual for 
your particular X terminal should document the display class string for your device If it doesn't, you can run xdm in debug 
mode and look at the resource strings that it generates for that device which will include the class string. 

When xdm starts a session, it sets up authorization data for the server. For local servers, xdm passes -auth filename on the 
server's command line to point it at its authorization data. For XDM CP servers xdm passes the authorization data to the 
server via the Accept XDM CP request. 

RESOURCES FILE 

Thexresources file is loaded onto the display as a resource database using xrdb. As the authentication widget reads this 
database before starti ng up, it usually contains parameters for that widget: 

xlogin*login.translations: #override\ 

Ctrl<Key>R: abort-display()\n\ 

<Key>F1: set-session-argument(failsafe) finish-field()\n\ 

<Key>Return: set-session-argument() finish-field)) 
xlogin*borderWidth: 3 
xlogin*greeting: CLIENTHOST 
#ifdef COLOR 

xlogin*greetColor: CadetBlue 
xlogin*failColor: red 
#endif 

Please note the translations entry; it specifies a few new translations for the widget that allow users to escape from the default 
session (and avoid troubles that may occur in it). N ote that if Override is not specified, the default translations are removed 
and replaced by the new value, not a very useful result as some of the default translations are quite useful (such as <Key>: 
insert-char o, which responds to normal typing). 

This file may also contain resources for the setup program and chooser. 

SETUP PRO GRAM 

Thexsetupfileisrun after the server is reset, but before the Login window is offered. T hefile istypically a shell script. It is 
run as root, so you should be careful about security. This isthe place to change the root background or bring up other 
windows that should appear on the screen along with the Login widget. 

In addition to any specified by DispiayManager.exportList, thefollowing environment variables are passed: 
display Theassociated display name 

PATH Thevalueof DisplayManager.DJSPLAY .systemPath 

SHELL Thevalueof DisplayManager,.DI,$PLAY .systemShell 

xauthority M ay be set to an authority file 

Note that si nee xdm grabs the keyboard, any other windows will not be able to receive keyboard input. They will be able to 
interact with the mouse however; beware of potential security holes here. If DispiayManager.Di SPLAY.grabServer isset, xsetup 
will not be able to connect to the display at all. Resources for this program can be put into the file named by 

DispiayManager.Di SPLAY.resources. 
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H ere is a sample xsetup script: 

#!/bin/sh 

# Xsetup 0 - setup script for one workstation 
xcmsdb </usr/X11R6/lib/monitors/alex.0 

xconsole -geometry 480x130-0-0 -notify -verbose -exitOnFail & 


AUTHENTICATION WIDGET 


The authentication widgdt reads a nanny password pair from the keyboard. N early every imaginable parameter can be 
controlled with a resource Resourcesforthiswidget should be put into the file named by DispiayManager. display, resources. 
All of these have reasonable default values, so it is not necessary to specify any of them. 


xlogin.Login.width, 
xlogin.Login.height, 
xlogin.Login.x, 
xlogin.Login.y 
xlogin.Login.foreground 
xlogin.Login.font 
xlogin.Login.greeting 

xlogin.Login.unsecureGreeting 


xlogin.Login.greetFont 
xlogin.Login.greetColor 
xlogin.Login.namePrompt 


xlogin.Login.passwdPrompt 

xlogin.Login.promptFont 
xlogin.Login.promptColor 
xlogin.Login.fail 

xlogin.Login.failFont 
xlogin.Login.failColor 
xlogin. Login. f ailT imeout 

xlogin. Login. translations 


The geometry of the Login widget is normally computed 
automatically. If you wish to position it elsewhere, specify each 
of these resources. 

The color used to display the typed-in username. 

The font used to display the typed-in username 
A string which identifiesthiswindow. The default isx window 

When X authorization is requested in the configuration file 
for this display and noneisin use, thisgreeting replaces the 
standard greeting. Thedefault isThis is an unsecure session. 
Thefont used to display the greeting. 

The color used to display the greeting. 

The string displayed to prompt for a username, xrdb strips 
trailing whitespace from resource values, so to add spaces at 
theend of the prompt (usually a nice thing), add spaces 
escaped with backslashes. Thedefault is Login:. 

The string displayed to prompt for a password. Thedefault is 

Password:. 

Thefont used to display both prompts 
The color used to display both prompts. 

A message that isdisplayed when the authentication fails. The 
default is Login incorrect. 

Thefont used to display thefailure message 
The color used to display thefailure message. 

The number of seconds that thefailure message isdisplayed. 
Thedefault is 30 . 

This specifies the translations used for the login widget. Refer 
to the X Toolkit documentation for a complete discussion on 
translations The default translation table is 


Ctrl<Key>H delete-previous-character() \n\ 

Ctrl<Key>D delete-character() \n\ 

Ctrl<Key>B move-backward-character!) \n\ 

Ctrl<Key>F move-forward-character() \n\ 

Ctrl<Key>A move-to-begining() \n\ 

Ctrl<Key>E move-to-end() \n\ 
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T he actions that are supported by the widget are 

delete-previous-character 
delete-character 



allow-all-access 


Ct rl<Key>K e rase - to - end - of -line() 

Ctrl<Key>U erase-line() \n\ 

Ctrl<Key>X erase-line() \n\ 



<Key>BackSpace delete-previous-character() \n\ 



<Key> insert-char() \ 


E rases the character before the cursor. 

E rases the character after the cursor. 

M oves the cursor backward. 

M oves the cursor forward. 

(Apologies about the spelling error.) M oves the cursor to the 
beginning of the editable text. 

M oves the cursor to the end of the editable text. 

E rases all text after the cursor. 

Erases the entire text. 

If the cursor is in the name field, proceeds to the password field; 
if the cursor is in the password field, checks the current name/ 
password pair. If the name/password pair is Valid, xdm starts the 
session. Otherwise thefailuremessageisdisplayed and the 
user is prompted again. 

T ermi nates and restarts the server. 

Terminates the server, disabling it. This action isnot accessible 
in the default configuration. There are various reasons to stop 
xdm on a system console, such as when shutting thesystem 
down, when using xdmsheii, to start another type of server, or 
to generally access the console. Sending xdm a sighup will 
restart thedisplay. See the subsection "Controlling XD M ." 
Resets theX server and starts a new session. Thiscan be used 
when the resources have been changed and you want to test 
them or when the screen has been overwritten with system 
messages 

I nserts the character typed. 

Specifies a single word argument that is passed to the session at 
startup. See the subsection "Session Program." 

Disables access control in the server. Thiscan be used when 
the .xauthority file cannot be created by xdm. Be very careful 
using this; it might be better to disconnect the machinefrom 
the network before doing this 


STARTUP PROGRAM 

Thexstartup file is typically a shell script. It is run as root and should be very careful about security. This is the place to put 
commands that add entries to /etc/utmp (the sessreg program may be useful here), mount users' home directories from file 
servers, display the message of the day, or abort the session if logins are not allowed. 



xdm 




In addition to any specified by DispiayManager.export 

DISPLAY 

HOME 

USER 

SHELL 

XAUTHORITY 


t, thefollowing environment variables are passed: 

T he associ ated display name 

The initial working directory of the user 

The username 

The value Of DispiayManager.Dl SPLAY .systemPath 
The value of DispiayManager.Dl SPLAY .systemShell 
M ay be set to an authority file 


N o arguments are passed to thescript. xdm waits until thisscript exits before starting the user session. If the exit value of this 
script is non-zero, xdm discontinues the session and starts another authentication cycle 

The sample xstartup file shown here prevents login while the file /etc/noiogin exists Thus, this is not a complete example, 
but simply a demonstration of the available functionality. 

H ere is a sample xstartup script: 


# This program is run as root after the user is verified 

if [ -f /etc/nologin ]; then 
xmessage -file /etc/nologin 

fi 

sessreg -a -1 $DISPLAY -x /usr/X11R6/lib/xdm/Xservers $USER 
/usr/X11R6/lib/xdm/GiveConsole 


SESSION PROGRAM 


Thexsession program is the command that is run as the 
In addition to any specified by DispiayManager.exportLisI 

DISPLAY 

HOME 

USER 

SHELL 

AUTHORITY 

KRB5CCNAME 


user's session. It is run with the permissions of the authorized user. 
:, thefollowing environment variables are passed: 

The associated display name 

The initial working directory of the user 

The username 

The value of DispiayManager.Dl SPLAY .userPath 
The user's default shell (from getpwnam) 

M ay be set to a nonstandard authority file 
M ay be set to a Kerberos credentials cache file 


At most installations, xsession should look in $home for afilexsession, which contains commands that each user would like 
to use as a session, xsession should also implement a system default session if no user-specified session exists. Seethe 
subsection "Typical U sage.” 

An argument maybe passed to this program from the authentication widget using the set-session-argument action. Thiscan 
be used to select different styles of session. One good useofthisfeatureistoallowtheuserto escape from the ordinary 
session when it fails This allows users to repair their own .xsession if it fails, without requiring administrative intervention. 
T he example following demonstrates thisfeature. 

Thisexample recognizes thespecial failsafe mode specified in the translations in thexresources file to provide an escape 
from the ordinary session. It also requires that the .xsession file be executable so you don't have to guess what shell it wants 
to use. 
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#!/bin/sh 


# This is the program that is run as the client 

# for the display manager. 


failsafe) 

exec xterm -geometry 80x24-0-0 


startup=$HOME/.xsession 
resources=$HOME/.Xresources 
if [ -f "$startup" ]; then 
exec "Sstartup" 

if [ -f "$resources" ]; then 
xrdb -load "$resources" 
fi 

twm & 

xman -geometry +10-10 & 

exec xterm -geometry 80x24+10+10 -Is 

fi 

The user's .xsession file might look something like thefollowing example D on't forget that thefile must have execute 
permission. 

#!/bin/csh 

# no -f in the previous line so .cshrc gets run to set $PATH 

xrdb -merge "$H0ME/.Xresources" 
emacs -geometry +0+50 & 
xbiff -geometry -430+5 & 
xterm -geometry -0+50 -Is 

RESET PROGRAM 

Symmetrical with xstartup, the xreset script is run after the user session has terminated. Run as root, it should contain 
commandsthat undo the effects of commands in xstartup, removing entries from /etc/utmp or unmounting directories from 
fi le servers. The environment variables that were passed to xstartup are also passed to xreset. 

A sample xreset script: 


# This program is run as root after the session ends 

sessreg -d -1 $DISPLAY -x /usr/X11R6/lib/xdm/Xservers $USER 
/usr/X11R6/lib/xdm/TakeConsole 


CONTROLLING THE SERVER 

xdm controls local servers using POSIX signals sighup is expected to reset the server, closing all client connections and 
performing other cleanup duties sigterm isexpected to terminate the server. If these signals do not perform the expected 
actions, the resources DisplayManager.DISPLAY. resetSignal and DisplayManager.DISPLAY.termSignal Can Specify alternate 
signals. 



To control remote terminals not using XD M C P, xdm searches the window hierarchy on the display and uses the protocol 
request Kiiiciient in an attempt to clean up the terminal for the next session. This may not actually kill all of thedients, as 
only those which have created windows will be noticed, xdmcp provides a more sure mechanism; when xdm closes its initial 
connection, the session isover and the terminal is required to doseall other connections 

CONTROLLING xdm 

xdm responds to two signals sighup and sigterm. When sent asiGHUP, xdm rereadsthe configuration file the access control file, 
and the servers file. For theservers file it notices if entries have been added or removed. If a new entry has been added, xdm 
starts a session on the associated display. Entries that have been removed are disabled immediately, meaning that any session 
in progress will determinated without notice and no new session will be started. 

When sent a sigterm, xdm terminates all sessions in progress and exits This can be used when shutting down the system, 
xdm attempts to mark its various subprocesses for ps(l) by editing the command-line argument list in place. Because xdm can't 
allocate additional space for this task, it is useful to start xdm with a reasonably long command line (using the full pathname 
should be enough). Each process which is servicing a display is marked -display. 

OTHER POSSIBILITIES 

You can use xdm to run a single session at a time using the 4.3 init options or other suitable daemon by specifying the server 
on the command line: 

xdm -server ":0 SUN-3/60CG4 local /usr/XI1R6/bin/X :0" 

Or you might have a file server and a collection of X terminals. The configuration for this is identical to that of the preceding 
sample, except the xservers file would look like this: 

extol:0 VISUAL-19 foreign 

exalt:0 NCD-19 foreign 

exploded NCR-TOWERVIEW3000 foreign 

Thisdirects xdm to manage sessions on all three of these terminals See the subsection "Controlling xdm" for a description of 
using signalsto enable and disable these terminals in a manner reminiscent of imt(8). 

LIMITATIONS 

One thing that xdm isn't very good at doing iscoexisting with other window systems To use multiple window systems on the 
same hardware, you'll probably be more interested in xinit. 

FILES 

<(Root>/lib/X11/xdm/xdm-config 
$H0ME/.Xauthority 
<(Root>/lib/X11/xdm/chooser 
<XRoot>/bin/X11/xrdb 
<XRoot>/bin/X11/X 
<(Root>/bin/X11/xterm 
<XRoot>/lib/X11/xdm/A<display>-<suffix> 

/tmp/K5C<display> Kerberos 

Note: <xRoot> refers to the root of the X11 install tree 


The default configuration file 

U ser authorization file where xdm stores keysfordientsto read 

The default chooser 

The default resource database loader 

The default server 

The default session program and failsafe client 
The default place for authorization files 
Credentials cache 


See Also 

X(l), xinit(l), xauth(l), Xsecurity(l), sessreg(l), Xserver(l) 

X Display M anager Control Protocol 
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AUTHOR 

Keith Packard (M IT X Consortium) 


X Version 11 Release6 


xdpyinfo 

xdpyinfo — D isplay information utility for X 

SYNOPSIS 

xdpyinfo [-display displayname] [-queryExtensions] [-ext ext ensi on-name] 

DESCRIPTION 

xdpyinfo is a utility for displaying information about an X server. It is used to examine the capabilities of a server, the 
predefined values for various parameters used in communicating between clients and theserver, and the different types of 
screens and visualsthat are available. 

By default, numeric information (opcode, base event, base error) about protocol extensions is not displayed. Thisinforma- 
tion can beobtained with the -queryExtensions option. Use of this option on servers that dynamically load extensions will 
likely cause all possible extensions to be loaded, which can be slow and can consume significant server resources 
Detailed information about a particular extension is displayed with the -ext extensionName option. If extensionName is all, 
information about all extensions supported by both xdpy-tnfo and theserver isdisplayed. 

ENVIRONMENT 

display To get the default host, display number, and screen 

SEE ALSO 

X(l), xwininfo(l), xprop(l), xrdb(l) 

AUTHOR 

Jim Fulton (M IT X Consortium) 

X Verson 11 Release 6 


Xf86_Accel 

xF86_Accei- Accelerated X W indow System servers for U NIX on x86 platforms with an S3, M ach8, M ach32, M ach64, 
P9000, AGX, ET4000/W 32, or 8514/A accelerator board 

SYNOPSIS 

XF86_S3 [idisplaynumber] [ option ] ... 

XF86_Mach8 [idisplaynumber] [ option ] ... 

XF86_Mach32 [idisplaynumber] [ option ] ... 

XF86_Mach64 [idisplaynumber] [ option ] ... 

XF86_P9000 [idisplaynumber] [ option ] ... 

XF86_AGX [idisplaynumber] [ option ] ... 

XF86_W32 [idisplaynumber] [ option ] ... 

XF86_8514 [idisplaynumber] [ option ] ... 




xf86_Accd 
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DESCRIPTION 

xf86_S3 is an 8-bit Pseudocolor, 16-bit TrueColor and 24-bit TrueColor server for S3 graphic accelerator boards. Note 16- 
bit and 24-bit operation is not supported on all S3 accelerator boards Refer to readme.S3 for details of which boards are 
supported at which depths. 

xF86_Mach8 isan 8-bit Pseudocolor server for ATI M ach8 graphic accelerator boards. 

xF86_Mach32 isan 8-bit Pseudocolor and 16-bit TrueColor server for ATI M ach32 graphic accelerator boards. Note 16-bit 
operation is not supported on all M ach32 accelerator boards 

xF86_Mach64 isan 8-bit Pseudocolor, 16-bit TrueColor, and 24-bit TrueColor server for ATI M ach64 graphic accelerator 
boards. Note 16-bit and 24-bit operation is not supported for all RAM DACs Refer to readme.M ach64 for details of which 
RAM DACs are supported at which depths. 

xf86_p 9000 isan 8-bit Pseudocolor, 16-bit TrueColor, and 24-bit TrueColor server for W atek Power 9000 (P9000) graphic 
accelerator boards. 

xf86_agx isan 8-bit Pseudocolor and 16-bit TrueColor server for AG X/XG A graphic accelerator boards. 

xf86_w32 isan 8-bit Pseudocolor server for ET4000/W 32, ET4000/W32i, and ET4000/W 32p graphic accelerator boards. 

xf86_8514 isan 8-bit Pseudocolor server for 8514/A graphic accelerator boards. 

These are derived from thex386 server provided with X11R5, and from thexssi4 server developed by Kevin M artin 
(<martin@cs.unc.edu>). 


CONFIGURATIONS 

The servers support the following chipsets 

XF86_S3 

XF86_Mach8 

XF86_Mach32 

XF86_Mach64 

XF86_P9000 

XF86_AGX 

XF86_W32 

XF86_8514 


86C911, 86C924, 86C801, 86C805, 86C8051, 86C928, 86C928- P, 
86C732 (Trio32), 86C764 (Trio64), 86C864, 86C868, 86C964, 86C968 
ATI Machs, ATI Mach32 
ATI Mach32 
ATI Mach64 

Diamond Viper vlb, Diamond Viper pci, Orchid P 9000 , and 
some clones (W eitek P 9000 ) 

AGX-010, AGX-014, AGX-015, AGX-016, XGA-1, XGA-2 
ET4000/W32, ET4000/W32i, ET3000/W32p 

IBM 85i 4 /a and true clones 


For S3, virtual resolutions up to (approximately) 1,152x800 are supported, using (up to) 1M B of display memory (the S3 
uses an internal width of 1,280 except for new revisions of some of thechips, hence 1M B can't support 1,152x900). Physical 
resolutions up to 1,280x1,024 (1,600x1,280 on some cards) are possible using 2M B or more of display memory. (Virtual 
resolution is dependent solely on the amount of memory installed, with the maximum virtual width being 2,048, and 
maximum virtual height is 4,096.) 

Similar resolutions are supported on the M ach64. Refer to readme. Mach64 for configuration details. 

Similar resolutions are supported on theMach32. FortheM ach32, the maximum virtual width is 1,536, and the maximum 
virtual height is 1,280. 

For M ach8, the maximum virtual width is 1,024. 

For 8514, the maximum resolution is 1,024x768. 

FortheAGX chips, maximum resolution depends upon the chip revision and amount of available display memory. Refer to 
readme. agx for configuration details. 
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FortheP9000, the virtual and phya'cal resolutions must be the same With sufficient memory, resolutions up to 
1,280x1,024 are supported. 

All the servers that support 24-bit visuals do so using a 32-bit per pixel configuration where 8 bits in every 32 bits is unused. 
This needs to betaken into account when calculating the maximum virtual display size that can be supported atthisdepth. 

OPTIONS 

In addition to the normal server options described in thexserver(l) manual page, these servers accept some more command- 
lineswitches, as described in thexFree86(l) man page 

T he M ach64, M ach32, S3, P9000, and AG X servers now support more than 8-bit color. T he M ach32 and AG X servers 
support 16-bit TrueColor and theM ach64, S3, and P9000 servers support 16-and 32-bit TrueColor. The 32-bit TrueColor 
mode only uses 24 bits per pixel for color information (giving you 16 million colors). These modes may be used by 
specifying the -bpp option as specified in thexFree86(l) man page. 

SETUP 

xFree86 uses a configuration file called xF86Config for its initial setup. 

SeethexF86Config(4/5) man page for general details H ere only the parts specific to thexF86_S3, xF86_Mach8, XF86jiach32, 
xF86_Mach64, xf86_p9000, xf86_agx, xf86_w32, and xf86_8514 servers are explained. 

Entries for theDevice section in thexF86Config file include the following: 

chipset "name" Specifies a chipset so the correct driver can be used. Possible 

chipsets are 

XF86_S3 

S3_generic: (for a standard 10 -driven server) 

Mmio_928: (for a memory-mapped 10-driven server on 
86C928, 86C732, 86C764, 86C864, 86C868, 86C964, and 
86C968 boards) 

xF86_Mach8, Machs (to force the M ach8 server to run on 
M ach32 boards) 

XF86_Mach32, Mach32 
XF86_Mach64, Mach64 
XF86_P9000 

vipervib (for theDiamond Viper VLB) 
viperpci (for the D iamond V iper PC I) 
orchidp9000 (for the 0 rchid P9000 and many 
generic P9000-based boards) 

XF86_AGX 

Agx-016 

Agx-015 

Agx-014 

Agx-010 

Xga-2 

Xga-1 


NOTE 


Only the agx- 016 , agx- 015 , agx- 014 , and xga-2 have been tested. RefertothexGA and AGx-010 section of readme. agx before 
attempting to use the other chipsets. 






XF86 W32 

Et4000w32 

Et4000w32i 

Et4000w32i_rev_b 

Et4000w32i_rev_c 

Et4000w32p_rev_a 

Et4000w32p_rev_b 

Et4000w32p_rev_c 

Et4000w32p_rev_d 

XF86_8514 

Ibm8514 

For boards with nonprogrammable clock chips, the clocks can 
be specified here (see xF86Conf ig(4/5)). T he P9000 server now 
no longer requires a Clocks line It will now work the same 
way as other servers with a programmable clock chip (that is, 
use the clocks as specified in the M odes). N ote, clocks over 
110 M H z are not recommended or supported by the P9000 
server. TheM ach64 server also does not require a Clocks line 
because the clocks are normally read di redly from the video 
card's BIOS. For the M ach64 server, thedocks given in the 
xF86Config file are ignored unless the no_bios_ciocks option is 
given (see below). 

For boards with programmable clock chips(except with the 
P9000 and AG X servers), the name of the clock chip is given. 
Possible values for the S3 server include "icd 206 ia", 

"ics9161a", "dcs2834", "8011412", "s3gendac", "s3 sdac", 
"U3025", "ti3026", "ics2595", "ics5300", "ics5342", "ch8391", 
"stg1703", and "ibm_rgb5xx". 

This specifies the type of RAM DAC used on the board. Only 
the S3, AGX, and W 32 servers use this. 

Normal— (S3, AG X) C ard does not have one of the other 
RAM DACsmentioned here. Thisoption is only required for 
the S3 server if the server i ncorrectly detects one of those other 
RAM DACs. TheAGX server does not yet auto-detect 
RAM DACs, this isthe default if no RAM DAC isspecified. 
Generic- (W 32) T his forces the W 32 server to treat the 
RAM DAC asagen eric VGA RAM DAC. 

Att20c490- (S3, AGX) Card has an AT&T 20C490 or AT&T 
20C491 RAM DAC. When thedac_8_bit option isspecified, 
these RAM DACs may be operated in 8-bit per RGB mode. It 
also allows 16bpp operation with 801/805/928 boards True 
AT&T 20C490 RAM DACs should be autodetected by the S3 
server. This RAM DAC must be specified explicitly in other 
cases. N ote that 8-bit per RG B mode does not appear to work 
with theWinbond 82C490 RAM DACsfwhich SuperProbe 
identifies as AT&T 20C492). 16bpp works fine with the 
Winbond 82C490. TheDiamond SS2410 RAM DAC is 
reported to be compatible when operating in 15bpp mode 
(not 16bpp). TheChrontel 8391 appears to be compatible in 
all modes 
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sci 5025 - (S3, AG X) Card has a Sierra SC 15025 or SC 15026 
RAM DAC. TheS3 server has code to autodetect this 
RAMDAC. 

sci 1 482- (S3) C ard has a Sierra SC 11482, SC 11483, or 
SC 11484 RAM DAC. The S3 server has code to autodetect 
this RAM DAC. 

sci 1485- (S3) C ard has a Sierra SC 11485, SC 11487 or 
SC 11489 RAM D AC. The S3 server will detect these 
RAM DACsasan scii482, so thisoption must be specified to 
take advantage of extra features (they support 16bpp, 15bpp, 
and 8bpp, while the others only support 15bpp and 8bpp). 
Bt485— (S3) Card has a BrookT ree Bt485 or Bt9485 
RAM DAC. T his must be specified if the server fai Isto detect it. 
Att2Oc505— (S3) Card has an AT&T 20C505 RAM DAC. 

This must be specified either if the server fails to detect the 
20C 505, or if the card hasaBt485 RAM DAC and there are 
problems using clocks higher than 67.5M H z. 

Att20 C 498 — (S3) C ard has an AT & T 20C 498 or 21C 498 
RAM DAC. T his must be specified if the server fai Isto detect it. 
Att22 C 498 — (S3) Card has an AT&T 22C498 RAM DAC. 

This must be specified if the server fails to detect it. 
ibm_rgb5i4— (S3) Card has an IBM RGB514 RAM DAC. This 
must be specified if the server fai Is to detect it. 
ibm_rgb524— (S3) Card has an I BM RGB524 RAM DAC. This 
must be specified if the server fails to detect it. 
ibm_rgb525— (S3) Card hasan IBM RGB 525 RAM DAC.This 
must be specified if the server fails to detect it. 
Ibm_rgb528-(S3) Card hasan IBM RGB528 RAM DAC. This 
must be specified if the server fails to detect it. 

Stg1700— (S3) Card has an STG1700 RAMDAC. This must be 
specified if theserver failsto detect it. 

Stg1703— (S3) Card has an STG1703 RAMDAC. This must be 

specified if theserver failsto detect it. 

S3gendac— (S3) Card hasan S3 86C708 G EN DAC. This 
RAMDAC does not support 8-bit per RGB mode (don’t 
specify the dac_8_bit option). It allows 16bpp operation with 
801/805 boards. There iscurrently no autodetection for this 
RAMDAC. 

S3_sdac— (S3) Card hasan S3 86C716 SDAC RAM DAC. 
This must be specified if the server failsto detect it. 
ics5300— (S3) Card hasan ICS5300 RAM DAC. Thismust be 
specified if theserver failsto detect it (theserver will recognize 
thisasan S3 GEN DAC which isOK). 
ics5342- (S3) Card hasen ICS5342 RAM DAC. Thismust be 
specified if theserver failsto detect it (theserver will recognize 
thisasan S3 SDAC which isOK). 

T13020— (S3) Card hasaTI ViewpointTi3020 RAM DAC. 
Thismust be specified if the server failsto detect the Ti3020. 
Note that pixel multiplexing will be used for this RAM DAC if 
any mode requires a dot clock higher than 70M Hz. 



T13025— (S3) C ard has a TI Viewpoint T i3025 RAM DAC. 
This must be specified if the server fails to detect the Ti3025. 
T13026- (S3) C ard has a TI V iewPoint T i3026 RAM D AC. 
This must be specified if the server fails to detect the Ti3026. 
Bt48i—(AGX) Card hasa BrookTree Bt481 RAM DAC. 

Bt482— (AGX) Card hasa BrookTree Bt482 RAM DAC. 
Herc_duai_dac-(AGX) Card (H ercules Graphite Pro) has 
both the 84-pin (Bt485 or AT & T 20C 505) and 44-pin (Bt481 
or Bt482) RAM D ACsinstalled. 

Herc_smaii_dac— (AGX) Card (H erculesGraphite Pro) has 
only the 44-pin (Bt481 or Bt482) RAM DAC installed. 

iOBase i oaddress Specifiesthe base addressfor extended 10 registers This is 

only used by the AGX server, and by the P9000 server for the 
Viper PC I. For details of how to use it, refer to readme. agx and 

README.P9000. 

MemBase me ma d d r e s s Specifiesthe hard-wired part of the linear framebuffer base 

address Thisoption is only used by theP9000, S3, M ach64, 
and M ach32 servers (and only when using a linear 
framebuffer). For the S3 server, the hard-wired part is the high 
10 bits of the 32-bit address (that is, me ma d d r e s s is masked with 
0XFFC00000). N ote: This should not be required for the 864 
and 964 chips where theentire framebuffer address is software- 
selectable Also, note that in versions prior to 3.1.1, the S3 
server used only the top 6 bits of mema ddr es s, and oRed it with 
0x3000000. To get the same behavior, or 0x3000000 with the 
value given previously. For the M ach32 server, the mask is 
0XF8O00000 (except for PC I cards, where the membase setting is 
ignored). 

Thisoption must be specified with the P 9000 server. With 
local busDiamond Vipers the value of memaddress can be 
either 0x80000000,0x20000000, or 0XA0000000. The default is 
0x80000000. Any value should work as long as it does not 
conflict with another device already at that address For the 
Viper PCI, refer to readme. P9000. For the Orchid P9000, the 
base address may be 0x00000000,0x00000000, or 0XE0000000, 
and must correspond the board's jumper setting. N ote Thes3 
server will normally probe for this address automatically. 
Setting thisoption overrides that probe. Thisisnot normally 
recommended because the failure of the server's probe usually 
indicates problems in using the linear framebuffer. 


NOTE 


TheM ach64 server requires thememory aperture ForlSA bus video cards, thismeansthat the aperturemust be enabled 
and the aperture addressmust beset to a valuelessthan 16M B (which meansthat, on ISA systemsonly, to usetheM ach64 
server you must have 12M B of main memory or less). N ormally the M ach64 server will use predefined values for this 
address, but setting thisoption will override the predefined address 
TheM ach32 server should not require the use of thisoption under normal circumstances. 
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COPBase baseaddress 

Instance instance 

S3MClk me me Ik 

S3MNAdjust M N 
S3RefClk ref cl k 

Option flags may be specified in either the Device section 

Option "opti onstri ng" 


T his sets the coprocessor base address for the AG X server. 

Refer to readme. agx for details 

ThissetstheXGA instance number for the AGX server. Refer 
to readme. agx for details 

This allows the video card's memory clock value to be 
specified. Thisisonly used for 805i, 864 and Trio32/64 cards 
and the value should not normally be given here for cards with 
an S3 G endac or T rio64. T his entry doesn't change the card's 
memory clock, but it is used to calculate the D RAM timing 
parameters For further details refer to readme.S3. 

This allows some memory timing parameters to be adjusted 
for DRAM cards Forfurther detai I s refer to readme. S3. 
Thisallows the PLL reference clock to be specified. This may 
be required for some cards that use the IBM RGB5xx 
RAM DACsThevalueisin MHz. For further detai Is refer to 

README.S3. 

■ the Display subsection of the xF86Contig file 
Allows the user to select certain options provided by the 
drivers. Currently thefollowing strings are recognized: 
Nomemaccess- (S3) Disable direct access to video memory. 

This option is ignored for the 864 and 964 chips 
Noaccei— (AGX, P9000) Disable hardware acceleration for the 
P9000, and disables the font cache with the AGX. 
vram_i28— (AGX, P9000) When memory probe fails use if 
you have 128Kx8VRAMs. 

vram_256— (AGX, P9000) When memory probe fails use if 
you don’t have 128Kx8 VRAM s. 

Noiineai — (S3 and M ach32) D isableuseof a linear-mapped 
framebuffer. 

Ti3020_curs- (S3) EnablestheTi3020’sinternal HW cursor. 
(Default) 

No_ti3020_curs- (S3) DisablestheTi3020’sinternal FI W 
cursor. 

sw_cursor- (S3, M ach32, M ach64, P9000, AGX) Disable the 
hardware cursor. 

Dac_8_bit— (S3, M ach32, M ach64, AGX) Enables 8-bit per 
RGB. Currently only supported with the 113020/5/6, Bt485, 

AT&T20C505, AT&T20C490/I, Sierra SC15025/6, AT&T20C498 and 
STG1700/3, IBM RGB5XX (S3 Server), Bt481 and Bt482 (AGX 
server), ATI68875/TLC34075/Bt885 (M ach32 server), ATI68875, 
TLC34075, ATI68860, ATI68880, STG1702, and STG1703 (M ach64 
server) RAM DACs. This is now set by default in the S3 server 
when one of the preceding RAM DACsotherthan the 

AT&T20C490/1 iS USed. 

Dac_6_bit — (S3) Force 6-bit per RGB in cases where 8-bit 
mode would automatically be enabled. 
sync_on_green— (S3, P9000) Enables generation of sync on the 
green signal on cards with Bt485, AT&T20C505,113020/5/6 or 
ibmrgb5xx RAM DACs Note: Although these RAM DACs 
support sync_on_green, it won't work on many cards because 
of the way they are designed. 



Power_savei — (S3 and M ach64) This option enables the server 
to use the power-savi ng features of V ESA D P M S-compatible 
monitors The suspend level iscurrently only supported for the 
M ach64 and for the 732,764,864,868,964,968 S3 chips. Refer 
to the xF86Conf ig(4/5) manual page for details of howto set 
the time-outs for the different levels of operation. Thisoption 
is experimental. 

intei_gx— (M ach32) Sets the hard-wired offset for the linear 
framebuffer correctly for the Intel GX Pro cards. This option 
is equivalent to setting the membase to 0x78000000. 
speajnercury— (S3) Enables pixel multiplex support for SPEA 
M ercury cards (928 +Bt485 RAM DAC). For these cards pixel 
multiplexing isrequired in order to use dot clocks higher than 
67.5 M H zand to access more than 1M B of video memory. 
Pixel multiplexi ng is currently supported only for 
noninterlaced modes, and modes with a physical width no 
smaller than 1,024. 

stb_pegasus— (S3) Enables pixel multiplex support for ST B 
Pegasus cards (928 + Bt485 RAM DAC). For these cards pixel 
multiplexing isrequired in order to use dot clocks higher than 
67.5 M FI z. Pixel multiplexing iscurrently supported only for 
noninterlaced modes, and modes with a physical width no 
smaller than 1,024. 

number_nine— (S3) Enables pixel multiplex support for 
N umber N ineGXelevel 10,11,12 cards (928 +Bt485 
RAM DAC). For these cards, pixel multiplexing isrequired in 
order to use dot clocks higher than 85M Hz. Pixel multiplexing 
is currently supported only for noninterlaced modes and 
modes with a physical width no smaller than 800. Thisoption 
is also required for some other N umber N inecards (for 
example, gxe64 and GXE64pro). 
diamond— (S3) Thisoption may be required for some 
Diamond cards (in particular, the 964/968 VRAM cards). 
eisa_wi000pro-(s3) Enables support for the E LSA W inner 
1000 PRO. Thisoption is not usually required because the 
board can beautodetected. 

eisa_wi000isa— (S3) Enables support for the ELSA Winner 
1000 ISA. Thisoption is not usually required because the 
board can beautodetected. 

eisa_w2000pro-(S3) Enables support for the E LSA W inner 
2000 PRO. Thisoption is not usually required because the 
board can beautodetected. 

pcijack—(S3) Enables a workaround for problems seen with 
some PC 1 928 cards on machines with a buggy SMC U ART. 
s3_964_bt485_vcik— (S3) Enables a workaround for possible 
problems on cards using the 964 and Bt485. 
genoa, stb, hercules, Or number_nine,— (S3) These options may 
be used to select different defaults for the blank delay settings 
for untested cards with IBM RGB5xx RAM DACsto avoid 
pixel-wrapping problems. 
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siow_vram— (S3) Adjusts theVRAM timings for cards using 
slow VRAM . This is required for some Diamond Stealth 64 
VRAM and Hercules Terminator 64 cards 
Fast_vram-(S3) AdjuststheVRAM timingsforfaster VRAM 
access There will be display errors and pixel garbage if your 
card can't support it. 

siow_dram_ref resh— (S3) Adjusts the D RAM refresh for cards 
with slow D RAM to avoid lines of corrupted pixels when 
switching modes 

No_biock_write— <Mach64) D isablesthe block write mode on 
certain typesofVRAM M ach64 cards If noise or shadows 
appear on thescreen, thisoption should remove them. 
Biock_write— (M ach64) Enables the block write mode on 
certain typesofVRAM M ach64cards NormallytheM ach64 
server will automatically determine if thecard can handle 
block write mode, but thisoption will override the probe 
result. 

No_bios_ciocks— (M ach64) The M ach64 server normally 
reads the clocks from the bios. Thisoption overrides the bios 
clocks and forces the server to use the clocks given in the 
XF86Config file. 

There are also numeroustuningoptionsfortheAGX server. 
Refer to readme. agx for details 

Notethat xFree86 hassome internal capabilities to determine what hardware it is running on. Thus normally the keywords 
chipset, clocks, and videorain don't have to be specified. But there may be occasions when this autodetection mechanism 
fails (for example, too high a load on the machine when you start the server). For cases like this one should first run the 
server on an unloaded machine look at the results of the autodetection (that are printed out during server startup), and then 
explicitly specify these parameters in the configuration file It is recommended that all parameters especially clock values, be 
specified in thexF86Config file. 

FILES 

<XRoot>/bin/XF86 S3 
<XRoot>/bin/XF86 Mach8 
<XRoot>/bin/XF86 Mach32 
<XRoot>/bin/XF86 Mach64 
<XRoot>/bin/XF86 P9000 
<XRoot>/bin/XF86 AGX 
<XRoot>/bin/XF86 W32 
<XRoot>/bin/XF86 8514 
/etc/XF86Config 
<XRoot>/llb/X11/XF86Config 
<XRoot>/llb/X11 /doc/README. agx 
<XRoot>/llb/X11/doc/README.P9000 
<XRoot>/lib/X11/doc/README.S3 
<XRoot>/llb/X11 /doc/README .W32 


The 8-, 16-, and 24-bit color X server for S3 

The 8-bit color X server for M ach8 

The 8- and 16-bit color X server for M ach32 

The 8-, 16-, and 24-bit color X server for M ach64 

The 8-, 16-, and 24-bit color X server for the P9000 

The 8- and 16-bit color X server for AGX andXGA 

T he 8-bit color X server for ET4000/W 32 

The 8-bit color X server for IBM 8514 and true compatibles 

Server configuration file 

Server configuration file (secondary location) 

Extra documentation for the AGX server 
Extra documentation for the P9000 server 
Extra documentation for the S3 server 
Extra documentation for the W 32 server 


N ote: <xRoot> refers to the root of theXll install tree. 





SEE ALSO 

X(l), Xserver(l), XFree86(l), XF86Config(4/5), xvidtune(l), xdm(l), xf86config(l), xinit(l) 

AUTHORS 

In addition to the authors of xFree86 the following people contributed major work to this server: Kevin M artin 
(martin@cs.unc.edu), Jon Tombs (tombs@xFree86.org), Rik Faith (faith@cs.unc.edu). (Did the overall work on the base 
accelerated servers) 

David Dawes (dawes@XFree86.org), Dirk H ohndel (hohndel@XFree86.org), D avid Wexdblat (dwex@XFree86.org). (M erged 
their work into xFree86.) 

Jon Tombs (tombs@xFree86.org), David Wexelblat (dwex@xFree86.org), David Dawes (dawes@xFree86.org), Amancio H asty 
(hasty@netcom.com), Robin Cutshaw (robin@XFree86.org), ISI Orbert D istler (Norbert.Distler@physik.tu-muenchen.de), Leonard 
N . Zubkoff (lnz@dandelion.com), H arald Koenig (koenig@tat.physik.uni-tuebingen.de), Bernhard Bender 
(br@eisa.mhs.compuserve.com), Hans Nasten (nasten@everyware.se). (Development and improvement of the S3-specific code.) 
Kevin Martin (martin@cs.unc.edu), Rik Faith (faitheos.unc.edu),TiagoGons(tiago@comosjn.hobby.m), H ansNasten 
(nasten@everyware.se), Scott Laird (lair@midway.uchicago.edu). (D evelopment and improvement Of the Mach8- and 8514/A- 
specific code.) 

Kevin M artin (martin@cs.unc.edu), Rik Faith (faith@cs.unc.edu), M ikeBernson (mike@mbsun.mib.org), M ark Weaver 
(niarkweaver@brown.edu), Craig Groeschel (craig@metroiink.com). (Development and improvement of theMach32-specific code 
Kevin M artin, (martin@cs.unc.edu). (D evelopment of the Mach64-specific code.) 

Erik Nygren (nygren@mit.edu), H arry Langenbacher(harry@brain.jpl.nasa.gov),ChrisM ason 

(cimtch@osfmaii.isc.rit.edu), Henrik H armsen (harmsen@eritei.se). (D evelopment and improvement of the P9000-specific 
code.) 

H enry W orth (henry .worth@amaii. amdahi. com). (D evelopment of the agx specific code.) 

Glenn Lai (gienn@cs.utexas.edu). (Development of the ET4B00/w32-specificcode.) 

See also thexFree86(l) manual page. 

BUGS 

Some S3 cards with Bt485 RAM DACsare currently restricted to dot-docks less than 85M Hz. 

TheP9000 server may still have problems with cards other than the Diamond Viper VLB. There may still be problems with 
VGA mode restoration, but these should almost never occur. Using physical resolutions different from the virtual resolution 
is not supported and is not possible with the P9000. Use at dot-docks greater than 110M Hz is not recommended and not 
supported. Diamond claims that 135M Hz isthe maximum clock speed, but some of its bt485S are not rated that high. If you 
do not have a 135M H zbt485 on your Viper, contact Diamond tech support and they will send you an RM A number to 
replace the board. Acceleration is being added in slowly. At the present, onlycopyArea, Movewindow, and DrawLine are 
implemented. 0 ther accelerated features are bei ng tested and may be available in the next release. T here seems to be a 
problem with oivwm when used with xdmand vt switching. The cursor will be messed up when you return to avT if the cursor 
changed while you were in the vt. 

CONTACT INFO 

xFree86 source isavailablefrom the FT P server ftp.xFree86.org and mirrors. Send e-mail to xFree86@xFree86.org for details 

XFree86 V€T30n 3.1.2 
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XF86_Mono 

xF86_Mono— 1-bit nonaccelerated X Window System serversfor U N IX on x86 platforms 

SYNOPSIS 

XF86 Mono [:displaynumber] [ option ] ... 


DESCRIPTION 

xF86_Mono is a 1-bit StaticG rey server for VGA and SuperVGA cards and for some other monochrome cards 


CONFIGURATIONS 

ThexF86_Mono server supports the following popular SuperVGA chipsets in monochrome mode 

ATI 18800, 18800-1, 28800-2, 28800-4, 28800-5, 28800-6, 68800-3, 

68800-6, 68800AX, 68800LX, 88800CX, 88800GX 
ET3000, ET4000, ET4000/W32 


Tseng 

Western Digital 
Genoa 

Trident 

NCR 

Compaq 

Oak 

Cirrus 


PVGA1, WD90C00, WD90C10, WD90C11, WD90C30, WD90C31, WD90C33 
GVGA 

TVGA8800CS, TVGA8900B, TVGA8900C, TVGA8900CL, TVGA9000 

77C22, 77C22E 

AVGA 

OTI067, OTI077, OTI087 

CLGD5420, CLGD5422, CLGD5424, CLGD5426, CLGD5428, CLGD5429, 
CLGD5430, CLGD5434, CLGD5436, CLGD6205, CLGD6215, CLGD6225, 
CLGD6235, CL6410, CL6412, CL6420, CL6440 


ThexF86_Mono server supports the following monochrome cards and resolutions 

Sigma L-View, LaserView PLUS (in lbppmode): 1,664x1,280 

Hyundai HGC-1280: l,280[l,472]xl,024 

Apollo M onochromecard (with ID 9) from Apollo workstations: 

1,280x1,024 

Hercules and compatibles cards 720x348 

Additionally, it supports generic VGA cards with a maximum virtual resolution of (approximately) 800x650. 

On supported SVGA chipsets, xF86_Mono will use up to 'A of display memory, which yields a maxi mum virtual resolution of 
(approximately) 1,664x1,260 with 1M B of display memory. xF86_Mono does not support the accelerated functions of the 
supported chipsets 


OPTIONS 

In addition to the normal server options described in thexserver(l) manual page, xF86_Mono accepts some more command- 
lineswitches as described in thexFree86(l) man page 


SETUP 

xFree86 uses a configuration file called xF86Contig for its initial setup. 

SeethexF86Config(4/5) man page for general details. Here only the xF86_Mono specific parts are explained. 

The Driver entry in screen section of thexF86Config file should beset to vga2forVGA and SVGA boards, and mono for non- 
VGA mono boards. If screen sections are present for both of these, the server will start in a dual-headed configuration. 
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Entries for theDevice section in thexF86Config file include the following: 


Specifies a chipset so the correct driver can be used. Possible 
chipsets forVGA2: 

ATI Vgawonder 

T Seng Et3000, et4000, et4000w32, et4000w32i, 

et4000w32p 

W estern D igital Pvgal, Wd90c00, wd90c10, wd90c30, 

wd90c31, wd90c33 


Genoa 
T rident 

NCR 

Cirrus 


Generic VGA 


Gvga 

Tvga8800cs, tvga8900b, tvga8900c, 
tvga8900cl, tvga9000 
Ncr77c22, ncr77c22e Compaq: cpq avga 
OAK: oti067, oti077, oti087 
Clgd5420, clgd5422, clgd5424, clgd5426, 
clgd5428, clgd5429, clgd5430, clgd5434, 
clgd5436, clgd6205, clgd6215, clgd6225, 
Clgd6235, C16410, C16412, C16420, C16440 
generic 


Possible chipsdtsfor mono: 

Hyundai hgci280 

Sigma sigmalview 

Apollo apollo9 

H ercules hercules 

Specifies the base address of the video memory. Thisoption is 
only used for the Sigma LaserViewcards Valid addresses for 
these cards are 0XA0000,0XB0000,0x00000,0x00000,0XE0000. The 
default isoxEoooo. 

Sets the black color to theRGB values specified. These values 
must be given as integers in the range 0-63. The default iso 0 
0.Thisoption isonly valid for the vga2 screen type. 
Setsthewhite color to theRGB values specified. These values 
must be given as integers in the range 0-63. The default is 63 
63 63. Thisoption is only valid for the vga2 screen type 
option “optionstring" Allowsthe user to select certain options provided bythe 

drivers. Currently thefollowing strings are recognized: 
legend- For Sigma Legend ET4000-based boards. This 
option enables a special dock-selection algorithm used on 
Legend boards, and M U ST be specified for these boards to 
function correctly. 

swap_hibit—For Western Digital/PVGAl chipsets Some 
Western Digital-based boards require the high-order dock- 
select lead to be inverted. It is not possible for the server to 
determine thisinformation at run-time. If the 9th clock in the 
list of clocks detected by the server is less than 30M hz, this 
option likely needs to beset. 
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Hibit_iow, hibit_high—For Tseng ET4000 chipsets. With 
some ET4000 cards, the server has difficulty getting the state 
of the high-order clocks select bit right when started from a 
high-resolution text mode T hese options allow the correct 
initial state of that bit to be specified. To find out what the 
correct initial state is, start the server from an 80x25 text 
mode This option is only needed if the clocks reported by the 
server when started from a high-resolution text mode differ 
from those reported when it is started from an 80x25 text 
mode 

8ciocks— For the PVGA1 chipset, the default is 4 clocks 
Some cards with thischipset may support 8 clocks. Specifying 
thisoption will allow the driver to detect and use the extra 
clocks 

i6ciocks— ForTrident tvga8900b and 8900c chipsets. Some 
newer boards using 8900B and 8900c chipsets actually support 
16 clocks rather than the standard 8 clocks. Such boards will 
havea TCK9002 or TCK9004 chip on them. Specifying this option 
will allow the driver to detect and use the extra 8 clocks. 
power_saver—Thisoption en ables the server to use the power 
saving features of V ESA D PM S-compatible monitors. T he 
suspend level iscurrently not supported. Refer to the 
xF86Config(4/5) manual page for detailsof how to set the time¬ 
outs for the different levels of operation. Thisoption is 
experimental. 

secondary—For the hgci280 and apoiio9 chipsets. Thisoption 
allows the use of these cards jumpered to the secondary 1 101 
memory address. These addresses are 

hgc1280: I/O 0X3B0-0X3BF, mem 0XB0000-0XBFFFF (prim.) 

I/O 0x390-0X39F, mem 0xC8000-0xCFFFF (sec.) 
apollo9: I/O 0X3B0-0X3BF, mem 0xFA0000-0xFDFFFF (prim.) 

I/O 0X3D0-0X3DF, mem 0XA0000-0XDFFFF (SBC.) 

xFree86 can detect the hgc -1280 on both primary and 
secondary address; fortheapoiio card the primary addressis 
used by default. 

Note that xFree86 hassome internal capabilities to determine what hardware it is running on. Thus, normally the keywords 
chipset, clocks, and videoram don't have to be specified. But there may be occasions when this autodetection mechanism 
fails, (for example, too high a load on the machine when you start the server). For cases like this, one should first run 
xF86_Mono on an unloaded machine look at the results of the autodetection (that are printed out during server startup) and 
then explicitly specify these parameters in the configuration file It is recommended that all parameters, especially clock 
values, be specified in thexF86Config file 

FILES 

<xRoot>/bin/xF86 Mono The monochrome X serverforVGA, SVGA and other 

monochrome cards 

/etc/xF86Config Server configuration file 

<xRoot>/iib/xii /xF86Config Server configuration file 

N ote: <xRoot refers to the root of the X11 install tree 
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SEE ALSO 

X(l), Xserver(l), XFree86(l), XF86Config(4/5), xf86config(l), xvidtune(l), xdm(l), xinit(l) 

BUGS 

There are no known bugs at this time, although we welcome reports e-mailed to the address listed below. 

CONTACT INFO 

xFree86 source isavailablefrom the FT P serverftp.xFree86.org. 

Send e-mail to xFree86@xFree86.org for details 

AUTHORS 

Refer to thexFree86(l) manual page. 
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XF86_SVGA 

xf86_svga— N onaccelerated SVGA X W indow System servers for U NIX on x86 platforms 

SYNOPSIS 

XF86 SVGA [:displaynumber] [ option ] ... 


DESCRIPTION 

xf86_svga isan 8-bit Pseudocolor, 16-bitTrueColorand 24-bit TrueColor server for Super VGA cards It is derived from 
the X386 server provided with xhrs. Note: 16-bit TrueColor is currently only supported for some Cirrus and ARK chips and 
24-bit T rueC olor is only supported for some C i rrus chi ps. 


CONFIGURATIONS 

ThexF86_svGA server supports thefollowing popular SuperVGA chipsets in 256-color mode Virtual resolutions up to 
(approximately) 1152x900 are supported, using (up to) 1M B of display memory. The Western Digital WD90C33 and some of 
the Cirrus chipsets support up to 2M B of display memory and virtual resolutions of 1,280x1,024 and higher. Some of the 
Cirrus chipsets also support 16bpp and 32bpp (truecolor) modeson certain configurations Some of theARK chipsets 
support 16bpp modeson certain configurations. Generic VGA cards are also supported at 8bpp 320x200 only. 


Tseng 

Western Digital 

Genoa 
T rident 
NCR 

Cirrus Logic 


ARK 

RealTek 

Compaq 

Oak 


18800, 18800-1, 28800-2, 28800-4, 28800-5, 28800-6, 68800-3, 
68800-6, 68800AX, 68800LX, 88800CX, 88800GX 
ET3000, ET4000, ET4000/W32 

PVGA1, WD90C00, WD90C10, WD90C11, WD90C24A, WD90C30, WD90C31, 

WD90C33 

GVGA 

TVGA8800CS, TVGA8900B, TVGA8900C, TVGA8900CL, TVGA9000 
77C22, 77C22E 

CLGD5420, CLGD5422, CLGD5424, CLGD5426, CLGD5428, 

CLGD5429,CLGD5430, CLGD5434, CLGD5436, CLGD6205, CLGD6215, 

CLGD6225, CLGD6235, CL6410, CL6412, CL6420, CL6440 

ARK1000PV, ARK1000VL, ARK2000PV 

RTG3106 

AVGA 

OTI067, OTI077, OTI087 
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Avance Logic 
Chips& Technology 
MX 

Video7 


AL2101, ALI2301, ALI2302, ALI2308, ALI2401 
65520, 65530, 65540, 65545 
MX68000, MX68010 
HT216-32 


Accelerated support is included for most of theCirruschipsets, and for theWestern Digital wD9@c3i andwD90C33 chipsets 
Accelerated support for the ET4000/W32 isimplemented in a separate server (seexF86_w32(l)). Users of boards based on ATI's 
M ach8, M ach32, and M ach64 chipsets should refer to thexF86_Mach8(l), xF86jiach32(l) and xF86jiach64(l) manual pages 
respectively. 

OPTIONS 

In addition to the normal server options described in thexserver(l) manual page, xf86_svga accepts some more command- 
lineswitches as described in thexFree86(l) man page 

SETUP 

xFree86 uses a configuration file called xF86Config for its initial setup. 

SeethexF86Config(4/5) man page for general details. Here only thexF86_svGA specific parts are explained. 

This server requires a screen section in thexF86Config file with the Driver entry set to svga. 

Entries for the Device section in thexF86Config file include 

chipset "name" Specifies a chipset so the correct driver can be used. Possible 

chipsets are 
ATI 
Tseng 

Western Digital 

Genoa 
T rident 

NCR 

Cirrus Logic 


RealTek 

ARK 

Compaq 

Oak 

Avance Logic 

Chips& Technology 
MX 

Video7 

Generic 


vgawonder 

et3000, et4000, et4000w32, 
et4000w32i, et4000w32p 
pvgal, wd90c00, wd90c10, wd90c24, 
wd90c30, wd90c31, wd90c33 
gvga 

tvga8800cs, tvga8900b, tvga8900c, 
tvga8900cl, tvga9000 
ncr77c22, ncr77c22e 
clgd5420, clgd5422, clgd5424, 
clgd5426, clgd5428, clgd5429, 
clgd5430, clgd5434, clgd5436, 
clgd6205, clgd6215, clgd6225, 
clgd6235, C16410, C16412, C16420, 
C16440 
realtek 

ark1000pv, ark1000vl, ark2000pv 
cpq_avga 

Oti067, oti077, oti087 

al2101, ali2301, ali2302, ali2308, 

ali2401 

Ct65520, ct65530, Ct65540, ct65545 

video7 

generic 



Allows the user to select certain options provided by the 
drivers. Currently thefollowing strings are recognized: 
legend- For Sigma Legend ET4O00-based boards. Thisoption 
enables a special clock-selection algorithm used on Legend 
boards, and M U ST be specified for these boards to function 
correctly. 

swap_hibit—For Western Digital/PVGAl chipsets Some 
Western Digital-based boards require the high-order dock- 
select lead to be inverted. It is not possible for the server to 
determine thisinformation at run-time. If the 9th clock in the 
list of clocks detected by the server is less than 30M hz, this 
option likely needs to beset. 

mbitjow, hibit_high— For Tseng ET4000 chipsets W ith some 
ET4000 cards, the server has difficulty getting the state of the 
high-order clocks select bit right when started from a high- 
resolution text mode. These options allow thecorrect initial 
state of that bit to be specified. To find out what the correct 
initial state is start the server from an 80x25 text mode This 
option is only needed if the clocks reported by the server when 
started from a high-resolution text mode differ from those 
reported when it is started from an 80x25 text mode. 

8ciocks— For the PVGA1 chipset, the default is 4 clocks 
Some cards with thischipset may support 8 clocks. Specifying 
thisoption will allow the driver to detect and use the extra 
clocks 

i6ciocks— ForTrident tvga8900b and 8900c chipsets. Some 
newer boards using 8900B and 8900c chipsets actually support 
16 clocks rather than the standard 8 clocks. Such boards will 
havea TCK9002 or TCK9004 chip on them. Specifying this option 
will allow the driver to detect and use the extra 8 clocks. 
probe_ciocks— For C irrus chipsets T he C irrus driver has a 
fixed set of clocks that are normally used. Specifying this 
option will force the driver to probe for clocks instead of 
reporting the built-in defaults. Thisoption isfor debugging 
purposes only. 

power_saver—Thisoption enables the server to use the power¬ 
saving features of V ESA D PM S-compatible monitors. T he 
suspend level iscurrently not supported. Refer to the 
xF86Config(4/5) manual page for detailsof how to set the time¬ 
outs for the different levels of operation. Thisoption is 
experimental. 

noaccei— For Cirrus and W D chipsets Thisoption disables 
the accelerated features for thecigd5426, cigd5428, wd90c24, 
wd90c3i, and wd90c33 chipsets 

fifo_conservative—For Cirrus chipsets. Thisoption sets the 
crt_fifo threshold to a conservative value for dot clocks above 
65M FI z. This reduces performance, but may help in 
eliminating problems with "streaks" on thescreen during 
BitBLT operations. 

fifo_aggressive—ForCirruschipsets. Thisoption sdts the 
crt_fifo threshold to an aggressive value for dot clocks above 
65M FI z. This may increase performance. 
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siow_dram— For C irrus chipsets This option sets the D RAM 
timingsforslow DRAM chips. 

fast_dram— For ET4000 and Cirrus chipsets. Thisoption sets 
the DRAM timingsfor fast D RAM chips 
no_2mb_banksei— For Cirrus chipsets Thisoption is required 
for Cirrus cards with 2M B of videoram, which is in the form of 
512kx8 D RAM s (4 chips) rather than 256kx4 D RAM s (16 
chips). 

no_bitbit — For C irrus chipsets This option disables use of 
hardware BitBLT. 

linear—Attempt a linear mapping of the framebuffer into 
high memory. C urrently only supported for some C irrus 
configurations 

med_dram, favour_bitblt, sw_cursor, clgd6225_lcd, mmio— M Ore 
Cirrus-specific options. Refer to /usr/xiiR6/iib/xn/doc/ 
readme . cirrus for a detai led description of C irrus options. 

Sets the selection of speedupsto use The optional selection 
string can takethefollowing values: 
none 
all 

If the selection string is omitted, or if the speedup option is 
omitted, the selection defaults to an. Some of theSpeedUps 
can only be used with the ET4000, WD90C31, and WD90C33 
chipsdts and others require a virtual resolution with a xdim of 
1024. SpeedU psthat won't work with a given configuration 
are automatically disabled. 

Disables the SpeedUp code This is equivalent to speedup 
none. 

This specifies the type of RAM DAC used on the board. Only 
the ark driver currently uses this. RAM DAC types recognized 
include 

Att20c490— AT&T 20C 490 or compatible 8-bit RAM DAC. 
Att20c498— AT&T 20C 498 or compatible 16-bit RAM DAC. 
zoomdac— RAM DAC used by the FI ercules Stingray Pro/V and 
64/V. 

stgi700— STG1700 or compatible RAM DAC. 

Note that xFree86 hassome internal capabilities to determine what hardware it is running on. Thus, normally the keywords 
chipset, clocks, and videoram don't have to be specified. But there may be occasions when this autodetection mechanism 
fails, (for example, too high a load on the machine when you start the server). For cases like this, you should first run 
xf86_svga on an unloaded machine look at the results of the autodetection (that are printed out during server startup), and 
then explicitly specify these parameters in the configuration file It is recommended that all parameters, especially clock 
values, be specified in thexF86Config file 




FILES 

<xRoot>/bin/xF86 sveA TheSVGA colorX server 

/etc/xF86Config Server configuration file 

<xRoot>/iib/xii /xF86Config Server configuration file 

<XRoot>/iib/xi 1 /doc /readme . ark Extra documentation for the ARK driver 

<xRoot>/iib/xii/doc/README.ati Extra documentation fortheATI vgawon-der driver 
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<XRoot>/lib/X11/doc/README.cirrus 
<XRoot>/lib/X11/doc/README.trident 
<XRoot>/lib/X11/doc/README.tseng 
<XRoot>/lib/X11/doc/README.Oak 
<XRoot>/lib/X11/doc/README.Video7 
<XRoot>/lib/X11/doc/README.WstDig 

Note: <xRoot> refers to the root oftheXll install tree. 

SEE ALSO 

X(l), Xserver(l), XFree86(l), XF86Config(4/5), xf86config(l), xvidtune(l), xdm(l), xinit(l) 

BUGS 

Bug reports are welcome, and should be e-mailed to the address listed below. 

CONTACT INFO 

xFree86 source isavailablefrom the FT P serverftp.xFree86.org. 

Send e-mail to xFree86@xFree86.org for details 

AUTHORS 

Refer to thexFree86(l) manual page. 
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Extra documentation for the C irrus driver 

Extra documentation for theTrident driver 

Extra documentation for the ET4000 and ET3000 drivers 

Extra documentation for the Oak driver 

Extra documentation fortheVideo7 driver 

Extra documentation for theWD/PVGA driver 


XF86_VGA16 

xf86 VGA 16— 4-bit nonaccelerated X W indow System server for U NIX on x86 platforms 

SYNOPSIS 

XF86 VGA16 [:displaynumber] [ option ] ... 

DESCRIPTION 

xf86_vgai6 isa 4-bit color server for vga cards. The default root visual for this server is staticCoior. It also includes support 
for the non-VGA monochrome cards described in thexF86_Mono(l) manual page. It may be run in a dual-headed configura¬ 
tion. 

CONFIGURATIONS 

The xf86_vgai6 server supports thefollowing popular svga chipsets in 16-color mode. 

ATI 18800, 18800-1, 28800-2, 28800-4, 28800-5, 28800-6, 68800-3, 

68800-6, 68800AX, 68800LX, 88800CX, 88800GX 

T seng ET4000 

Trident TVGA8800CS, TVGA8900B, TVGA8900C, TVGA8900CL, TVGA9000 

C irrus CL6410, CL6412, CL6420, CL6440 

Oak OTI067, OTI077, OTI087 

Additionally, it supports generic VGA cards 

xf86_vgai 6 does not support the accelerated functions of the supported chipsets. 
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OPTIONS 

In addition to the normal server options described in thexserver(l) manual page, xf86_vgai6 accepts some more command- 
lineswitches, as described in thexFree86(l) man page 


SETUP 

xFree86 uses a configuration file called xF86Contig for its initial setup. 

SeethexF86Config(4/5) man page for general details. Here only the xf86_vgai6 specific parts are explained. 

The Driver entry in the screen section of thexF86Config file should beset to vgai6.T o run in dual-headed configuration, 
there should also be a screen section with the D river entry si to mono. 


Entries for the Device section in the xF86Conf ig file indude the following: 


Option "opt 


Specifies a chipset so the correct driver can be used. Possible 
chipsets are 

ATI vgawonder 

T Seng et4000, et4000w32, et4000w32i, et4000w32p 

Trident tvga8800cs, tvga8900b, tvga8900c, 

tvga8900cl, tvga9000 

C irrus C16410 , cl6412, cl6420, C16440 

Oak oti067, oti077, oti087 

Generic VGA generic 


Allows the user to select certain options provided by the 
drivers. Currently, thefollowing strings are recognized: 
legend— For Sigma Legend ET4O00-based boards. Thisoption 
enables a special clock-selection algorithm used on Legend 
boards, and M U ST be specified for these boards to function 
correctly. 

hibit_iow, hibit_high— For Tseng ET4000 chipsets. W ith some 
ET4000 cards, the server has difficulty getting the state of the 
high-order clocks select bit right when started from a high- 
resolution text mode. These options allow thecorrect initial 
state of that bit to be specified. To find out what the correct 
initial state is, start the server from an 80x25 text mode This 
option is only needed if the clocks reported by the server when 
started from a high-resolution text mode differ from those 
reported when it is started from an 80x25 text mode. 
power_saver—Thisoption enables the server to use the power 
saving features of V ESA D PM S-compatible monitors. T he 
suspend level is currently not supported. 

Refer to the xF86Config(4/5) manual page for details of howto 
set the time-outs for the different levels of operation. This 
option is experimental. 


Notethat xFree86 hassome internal capabilities to determine what hardware it is running on. Thus normally the keywords 
chipset, clocks, and videoram don't have to be specified. But there may be occasions when this autodetection mechanism 
fails, (for example, too high a load on the machine when you start the server). For cases like this, you should first run xf86 
vgai6 on an unloaded machine look at the results of the autodetection (that are printed out during server startup), and then 
explicitly specify these parameters in the configuration file It is recommended that all parameters, especially clock values, be 
specified in thexF86Config file. 
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FILES 

<XRoot>/bin/XF86 VGA16 

/etc/XF86Config 

<XRoot>/lib/X11/XF86Config 

N ote: <xRoot> refers to the root of the X11 install tree. 


The 16-color X server 
Server configuration file 
Server configuration file 


SEE ALSO 

X(l), Xserver(l), XFree86(l), XF86Config(4/5), XF86 Mono(l), xf86config(l), xvidtune(l), xdm(l), xinit(l) 

CONTACT INFO 

xFree86 source isavailablefrom the FT P serverftp.xFree86.org. 

Send e-mail to xFree86@xFree86.org for details 

AUTHORS 

The primary developer of this server is G ertj an Akkerman (akkerman@dutiba .twi.tudeift.nl). 

See also thexFree86(l) manual page. 

XFree86 V€T30n 3.1.2 


xf86config 

xf86config—Generate an xF86Config file 

SYNOPSIS 

xf86config 

DESCRIPTION 

xf86config isan interactive program for generating an xF86Configfiie for use with xFree86 X servers. 

FILES 

<xroot>/iib/xii/cards Video cards database 

SEE ALSO 

XFree86(l), XF86Config(4/5), reconfig(l) 

AUTHOR 

H arm H anemaayer 

XFree86 VffSOn 3.1.1 


xfd 

xfd- D isplay all the characters in an X font 

SYNOPSIS 

xfd [-options ...] -fn font name 
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DESCRIPTION 

Thexfd utility creates a window containing the name of the font being displayed, a row of command buttons, several lines of 
text for displaying character metrics, and a grid containing one glyph per cell. The characters are shown in increasing order 
from left to right, top to bottom. The first character displayed at the top left will be character number 0 unless the-start 
option has been supplied, in which case the character with the number given in the-start option will be used. 

The characters are displayed in a grid of boxes, each large enough to hold any single character in the font. Each character 
glyph isdrawn usingthePoiyTexti6 request (used bythexiib routine xDrawstrtngi6). If the-box option isgiven, a rectangle 
will be drawn around each character, showing where an imageTexti6 request (used bythexiib routinexDrawimagestringi6) 
would cause background color to be displayed. 

The origin of each glyph is normally set so that the character isdrawn in the upper left corner of the grid cell. However, ifa 
glyph has a negative left bearing or an unusually large ascent, descent, or right bearing (as isthe case with cursor font), some 
characters may not appear in their own grid cells The -center option may be used to force all glyphs to be centered in their 
respective cells 

All the characters in the font may not fit in the window at once To see the next page of glyphs, press the N ext button at the 
top of the window. To see the previous page, press Prev. To exit xfd, press Q uit. 

Individual character metrics (index, width, bearings, ascent, and descent) can bedisplayed at the top of the window by 
clicking on thedesired character. 

The font name displayed at the top of the window is the full name of the font, as determined by the server. Seexisfonts for 
ways to generate lists of fonts as well as more detailed summaries of their metrics and properties. 


OPTIONS 


xfd accepts all of the standard toolkit command-line options along with the following additional options 


-columns numcol s 


This option specifies the font to bedisplayed. This can also be 
set with the FontGrid font resource. A font must be specified. 
This option indicates that a box should bedisplayed outlining 
the area that would be filled with background color by an 
imageText request. This can also be set with the FontGrid 
boxchars resource. The default isFaise. 

Thisoption indicates that each glyph should be centered in its 
grid. This can also beset with the FontGrid center-chars 
resource. The default isFaise. 

Thisoption specifies the glyph index of the upper left corner 
of the grid. This is used to view characters at arbitrary 
locations in the font. This can also beset with the FontGrid 
startchar resource The default iso. 

Thisoption specifies the color to be used if imageText boxes 
are drawn. Thiscan also be set with theFontGrid boxcoior 
resource. 

Thisoption specifies the number of rows in the grid. Thiscan 
also be set with theFontGrid ceiiRows resource 
Thisoption specifiesthe number of columns in thegrid. This 
can also be set with theFontGrid ceiicoiumns resource. 


WIDGETS 

In order to specify resources, it is useful to know the widgets that compose xfd. In the notation below, indentation indicates 
hierarchical structure. The widget class name is given first, followed by thewidgdt instance name. The application class name 
is xfd. 
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Paned pane 

Label fontname 

Command quit 
Command [rev 

Label select 
Label metrics 
Label range 
Label start 

Form form 
FontGrid grid 


FONTGRID RESOURCES 

The FontGrid widget is an application-specific widget, and a subclass of the Simple widget in the Athena widget set. The 
effects and instance names of this widget's resources are given in the "Options" subsection. C apitalize thefirst letter of the 
resource instance name to get the corresponding class name 


APPLICATION SPECIFIC RESOURCES 


T he instance names of the application-specific resources are given in thefollowing list. C apitalize thefirst letter of the 
resource instance name to get the corresponding class name These resources are unlikely to be interesting unless you are 
localizing xfd for a different language. 


selectFormat 


metricsFormat 


rangeFormat 


startFormat 


nocharFormat 


Specifies a printf-style format string used to display informa¬ 
tion about the selected character. The default ischaracter 
ox%02x%02x (%u,%u) (%#o,%#o). The arguments that will come 
after the format string are 

char.bytel, char.byte2, char.bytel, char.byte2,char.bytel, 
char.byte2. char.bytel is byte 1 of the selected character. 
char.byte2 is byte 2 of the selected character. 

Specifies a printf-style format string used to display character 
metrics The default is width %d; left %d, right %d; ascent 
%d, descent %d (font %d, %d). The arguments that will come 
after the format string are the character metrics width, 

Ibearing, rbearing, character ascent, character descent, font 
ascent, and font descent. 

Specifies a printf-style format string used to display the range 
of characters currently being displayed. The default is range: 
0x%02x%02x (%u,%u) thru 0x%02x%02x (%u,%u).Thearguments 
that will come after the format string are thefollowing fields 
from thexFontstruct that is returned from opening the font: 

min_byte1, min_char_or_byte2, min_byte1, min_char_or_byte2, 
max_byte1, max_char_or_byte2, max_byte1, max_char_or_byte2. 

Specifies a printf-style format string used to display informa¬ 
tion about the character at the upper left corner of the font 
grid. The default is upper left: 0x%04x (%d,%d). T he 
arguments that will comeafter theformat string are the new 
character, the high byte of the new character, and the low byte 
of the new character. 

Specifies a printf-style format string to display when the 
selected character does not exist. The default is no such 
character 0x%02x%02x (%u,%u) (%#o,%#o. The arguments that 
will comeafter theformat string are the same as for the 
select-Format resource. 
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SEE ALSO 

x(l), xisfonts(l), xrdb(l), xfontsei(l), X Logical Font Description Conventions 

BUGS 

The program should skip over pages full of nonexistent characters. 

AUTHOR 

Jim Fulton (M IT X Consortium); previous program of the same name by M ark Lillibridge (M IT Project Athena) 

X Version 11 Release6 

XFree86 

xFree86— X11R6for U NIX on x86 platforms 

DESCRIPTION 

xFree86 is a collection of X servers for UN IX-likeOSson Intel x86 platforms. This work is derived from X386ni.2, which was 

contributed to xhrs by Snitily Graphics Consulting Service 

CONFIGURATIONS 

xFree86 operates under thefollowing operating systems: 

■ SVR3.2: SCO 3.2.2, 3.2.4, ISC 3.x, 4.x 

■ SV R4.0: ESI X, M icroport, D ell, U H C, C onsensys, M ST, I SC, AT & T, N C R 

■ SVR4.2: Consensys, Univel (UN IXWare) 

■ Solaris (x86) 2.1,2.4 

■ FreeBSD 1.1.5, 2.0, 2.0.5, N dtBSD 1.0 (i386 port only) 

■ BSD/386 version 1.1 and BSD/OS 2.0 

■ M ach (from C M U) 

■ Linux 

■ Amoeba version 5.1 

■ M inix-386vm version 1.6.25.1 

■ LynxOSAT versions2.2.land 2.3 

NETWORK CONNECTIONS 

xFree86 supports connections made using the following reliable byte-streams: 

Local xFree86 supports local connections via Streams pipe via various 

mechanisms, using thefollowing paths (n represents the 
display number): 

/dev/X/server.n (SVR3 and SVR4) 

/dev/X/Nserver.n (SVR4) 

/dev/XnS and /dev/XnR (SCO SVR3) 

In SVR4.0.4, if the Advanced Compatibility Packageis 
installed, and in SVR4.2, xFree86 supports local connections 
from clients for SCO XSight/O DT, and (with modifications 
to the binary) clients for ISC SVR3. 

UNIX Domain xFree86 uses/tmp/.xii-unix/xnasthefilenamefor the socket, 

where n is the display number. 
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TCPIP xFree86 listens on port htons(6000+n), where n isthedisplay 

number. 

Amoeba RPC This is the default communication medium used under native 

Amoeba. Note that under Amoeba, the server should be 
started with a host name: di spi aynumber argument. 

ENVIRONMENT VARIABLES 

For operating systems that support local connections other than U NIX D omain sockets (SV R3 and SV R4), there is a 
compiled-in list specifying the order in which local connections should be attempted. This list can be overridden by the 
xlocal environment variable described next. If the display nameindicatesabest-choiceconnection should bemadeffor 
example, 10.0), each connection mechanism istried until a connection succeeds or no more mechanismsare available Note: 
FortheseOSs, the UN IX Domain socket connection istreated differently from the other local connection types To use it 
the connection must be made to umx:0.0. 

T he xlocal environment variable should contain a list of one more of the following: 


which represent SVR4 Named Streams pipe, Old-style USL Streams pipe, SCO XSight Streams pipe and ISC Streams pipe, 
respectively. You can select a single mechanism (for example, xlocal=named), or an ordered list, for example, 


This variable overrides the compiled-in defaults. For SVR4 it isrecommended that named be the fi rst preference connection. 
The default setting is 

PTS: NAMED: ISC: SCO. 

To globally override thecompiled-in defaults, you should define (and export if using shor ksh) xlocal globally. If you use 
startx/xinit, the definition should be at the top of your .xinitrc file. If you usexdm, the definitions should be early on in 
the <XRoot>/lib/X11 /xdm/Xsession Script. 

OPTIONS 

In addition to the normal server options described in thexserver(l) manual page, xFree86 accepts the foil owing command¬ 
line switches: 

xx specifiestheVirtual Terminal device number that xFree86 
will use. Without thisoption, xFree86 will pick the first 
available Virtual T erminal that it can locate Thisoption 
applies only to SVR3, SVR4, Linux, and BSD OSs with the 
syscons or pcvt driver. 

C auses the server to exit after the device probi ng stage. T he 
xF86Config fileisstill used when thisoption isgiven.so 
information that can be auto detected should be commented 
out. 

Suppresses most informational messages at startup. 

Set number of bits per pixel. T he default is 8. Legal values are 
8,15,16, 24, 32. N ot all servers support all values. 

Sdts RGB weighting at 16 bpp. The default is 565. This applies 
only to those servers that support 16 bpp. 

Sdts the gamma correction, vai ue must be between 0.1 and 10. 
T he default is 1.0. T his value is applied equally to the R, G, 
and B values N ot all servers support this. 
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-rgamma value 

-ggamma value 

-bgamma value 

-showconfig 

-verbose 

-xf86config file 

KEYBOARD 

M ultiple key presses recognized directly by xFree86 are 
CtrUAIt46ackspace 

CtrUAIt4Keypad-Plus 
C trl 4A It+K eypad-M inus 
Ctrl-fAlt+Fl... F12 


Sdtsthe red gamma correction, value must be between 0.1 and 
10. The default is 1.0. Not all servers support this 
Sdts the green gamma correction, value must be between 0.1 
and 10. The default is 1.0. N ot all servers support this. 

Sets the blue gamma correction, value must be between 0.1 
and 10. The default is 1.0. N ot all servers support this. 

Prints out a list of screen drivers configured in the server. 

M aximizesinformation printed at startup (morethan the 
default). 

Reads the server configuration from file This option is only 
available when the server is run as root (that is, with real- 
UID 0). 

Prevents the server from detaching its initial controlling 
terminal. Thisoption isonly useful when debugging the 
server. 


Immediately kills the server- no questions asked. (Can be 
disabled by specifying "Dontzap" in the Server-Flags section of 
the XF86Config file) 

Changes video mode to next one specified in the configuration 
file, (increasing video resolution order). 

Changes video mode to previous one specified in the 
configuration file, (decreasing video resolution order). 

For BSD systems using thesysconsdriver and Linux, these 
keystroke combinations are used to avitch to Virtual Console 
1 through 12. 


SETUP 

xFree86 uses a configuration file called xF86Config for its initial setup. Refer to the xF86Config(4/5) manual page for more 
information. 


FILES 

<XRoot>/bin/XF86 SVGA 
<XRoot>/bin/XF86 Mono 
<XRoot>/bin/XF86 S3 
<XRoot>/bin/XF86 Mach8 
<XRoot>/bin/XF86 Mach32 
<XRoot>/bin/XF86 Mach64 
<XRoot>/bin/XF86 P9000 
<XRoot>/bin/XF86 AGX 
<XRoot>/bin/XF86 W32 
<XRoot>/bin/XF86 8514 
/etc/XF86Config 

<(Root>/lib/X11/XF86Config.hostname 

<XRoot>/lib/X11/XF86Config 

<(Root>/bin/ 


The color SVGA X server 

The monochrome X server for VGA and other mono cards 

The accelerated S3 X server 

The accelerated Machs X server 

The accelerated Mach32 X server 

The accelerated Mach64 X server 

The accelerated P9000 X server 

The accelerated agx X server 

The accelerated ET4000/W32 X server 

The accelerated 8514/a X server 

Server configuration file 

Server configuration file 

Server configuration file 

Client binaries 
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<(Root>/include/ 

<XRoot>/lib/ 

<XRoot>/lib/X11/fonts/ 

<XRoot>/lib/X11/rgb.txt 
<XRoot>/lib/X11 /XErrorDB 
<XRoot>/lib/X11/app-defaults/ 

<XRoot>/man/man?/ 

/etc/Xn.hosts 

Note: <xRoot> referstotherootoftheXll install tree. 


Header files 

Libraries 

Fonts 

Color namesto RGB mapping 
C lient error message database 
C lient resource specifications 
M anual pages 

Initial access control list for display n 


SEE ALSO 

X(l), Xserver(l), xdm(l), xinit(l), XF86Config(4/5), xf86config(l), XF86 SVGA(l), XF86 VGA16(1), XF86 Mono(l), XF86 Accel(l), 
xvidtune(l) 


AUTHORS 

For xiiR5, xf86 1.2 was provided by the following: 

ThomasRoell (roell@informatik.tu-muenchen.de; server and SVR4 stuff), M ark W . Snitily (mark@sgcs.com sgcs; SVR3 
support, X Consortium Sponsor), and many more people out there on the N et who helped with ideas and bugfixes 
xFree86 was integrated into xiiR6 by the following team: 

Stuart Anderson (anderson@metrollnk.com), Doug Anson (danson@lgc.com), GertjanAkkerman 

(akkerman@dutiba.twi.tudelft.nl), M ike BernSOn (mike@mbsun.mlb.org), Robin Cutshaw (robin@XFree86.org), David D awes 
(dawes@XFree86.org), M arc Evans(marc@XFree86.org), Pascal H aible (haible@izfm.uni-stuttgart .de), M atthieu H errb 
(Matthieu.Herrb@laas.fr), Dirk Hohndel (hohndel@XFree86.org), David Holland (davidh@use.com), Alan Hourihane 
(alanh@fairlite.demon.co.uk), Jeffrey H SU (hsu@soda.berkeley.edu), G lenn Lai (glenn@cs.utexas.edu), Ted Lemon 
(mellon@ncd.com), Rich M Urphey (rich@XFree86.org), H ansN asten (nasten@everyware.se), M ark Snitily (mark@sgcs.com), 
Randy Terbush (randyt@cse.um.edu), Jon Tombs(tombs@xFree86.org), KeesVerstoep (versto@cs.vu.ni), Paul Vixie 
(paui@vix.com), M ark Weaver (Mark weaver@brown.edu), David Wexelblat (dwex@xFree86.org), Philip Wheatley 
(Philip.Wheatley@ColumbiaSC.NCR.COM), T homas WOlfram (wolf@prz. tu-berlin.de), and 0 rest ZbOTOWSki 
(orestz@eskimo.com). 

ThexFree86 enhancement package was provided by 
David Dawes, dawes@XFree86.org 

Glenn Lai, glenn@cs.utexas.edu 

JimTsillaS, jtsilla@ccs.neu.edu 
David Wexelblat, dwex@XFree86.org 


Dirk Hohndel, hohndel@XFree86.org 

Amancio H asty J r., hasty@netcom. com 
Rich M urphey, rich@XFree86.org 


Release coordination, administration of FTP repository and 
mailing lists. Source tree management and integration, 
accelerated server integration, fixing, and coding. 

TheSpeedU p code for ET4000-based SVGA cards, and ET4000/ 
W32 accelerated server. 

M any server speedupsfrom thefX386 series of enhancements 
I ntegration of the fX386 code into the default server, many 
driver fixes and driver documentation, assembly oftheVGA 
card/monitor database development of the generic video 
mode listing. Accelerated server integration, fixing, and 
coding. 

Linux-shared libraries and release coordination. Accelerated 
server integration and fixing. Generic administrivia and 
documentation. 

Porting to 386BSD version 0.1 and XS3 development. 

Ported to 386BSD version 0.1 based on the original port by 
Pace W illison. Support for 386BSD, FreeBSD, and NetBSD. 
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Robert Baron, Robert.Baron@ernst.mach.cs.cmu.edu 

Orestzborowski, orestz@eskimo.com 

Doug Anson, danson@lgc.com 

David Holland, davidh@use.com 

David M cCuHough, davidm@stallion.oz.au 

M ichael Rohleder, michael.rohleder@stadt-frankfurt.de 

KeesVerstoep, versto@cs.vu.rn 

M arc Evans, Marc@XFree86.org 

Philip Homburg, phiiip@cs.vu.nl 

Thomas M ueller, tm@systrix.de 

J on T ombs, tombs@XFree86. org 

Harald Koenig, koenig@tat.physik.uni-tuebingen.de 

Bernhard Bender, br@elsa.mhs.compuserve.com 

Kevin M artin, martin@cs.unc.edu 

Rik Faith, faith@cs.unc.edu 
Tiago Gons, tiago@comosjn.hobby.nl 
HansNasten, nasten@everyware.se 

MikeBernSOn, mike@mbsun.mlb.org 

M ark W eaver, Mark Weaver@brown.edu 

C raig G roeschel, craig@metrolink.com 

H enry WOrth, Henry.Worth@amail.amdahl.com 

Erik N ygren, nygren@mit.edu 

Harry Langenbacher, harry@brain.jpl.nasa.gov 

Chris M ason, mason@mail.csh.rit.edu 

H enrik H armsen, harmsen@eritel.se 

Simon Cooper, scooper@vizlab.rutgers.edu 

H arm H anemaayer, hhanemaa@cs.ruu.m 

M ike Tierney, floyd@eng.umd.edu 

Bill Conn, conn@bnr.ca 

Brad Bosch, brad@lachman.com 

Alan H ourihane alanh@fairlite.demon.co.uk 

M arc La France, Marc.La-France@ualberta.ca 

Steve Goldman, sgoldman@encore.com Oak 

J orge D elgado, ernar@dit .upm.es 

Bill Conn, conn@bnr.ca 

Paolo Severini, lendl@dist.dist.unige.it 

Ching-Tai Chiu, cchiu@netcom.com 

M anfred Brands, mb@oceonics.m 

Randy H endry, randy@sgi.com 

Frank Dikker, dikker@cs.utwente.nl 

RegisCridlig, cridlig@dmi.ens.fr 

Jon Block, block@frc.com 


Ported to M ach. 

Ported to Linux. 

Ported to Solaris x86. 

Ported to Solaris x86. 

Ported to SCO SVR3. 

Ported to ISC SVR3. 

Ported to Amoeba based on Leendertvan Doorn'soriginal 
Amoeba port of X11R5. 

Ported to OSF/1. 

Ported to M inix-386vm. 

Ported to LynxO S. 

S3 server and accelerated server coordination. 

S3 server development. 

S3 server development. 

0 verall work on the base accelerated servers (AT I and 8514/ 
A), and M ach64 server. 

0 verall work on the base accelerated servers (AT I and 8514/A). 
M ach8 and 8514/A server development. 

M ach8, 8514/A, and S3 server development and BSD/386 
support. 

M ach32 server development. 

M ach32 server development. 

M ach32 server development. 

AGX server. 

P 9000 server. 

P 9000 server. 

P 9000 server. 

P 9000 server. 

Cirrus accelerated code (based on work by Bill Reynolds). 
Cirrus accelerated code and ARK driver. 

W D accelerated code. 

W D accelerated code. 

WD 90C24A support. 

Trident SVGA driver 
ATI vgawonder SVGA driver 
067/077 SVGA driver. 

Oak SVGA driver, and 087 accelerated code. 

W D accelerated code. 

AL2101 SVGA driver. 

Avance Logic ALI SVGA driver. 

Cirrus64xxSVGA driver. 

Cirrus6440 support in thed64xx SVGA driver. 

MX SVGA driver. 

C hips & Technology driver. 

C hips & Technology driver. 



M ike H ollick, hollick@graphics.cis.upenn. 
PeterTrattler, peter@sbox.tu-graz.ac.at 
Craig Struble cstruble@acm.vt.edu 
Gertjan Akkerman, akkerman@dutiba.twi.tui 
Davor M atic, dmatic@Athena.MIT.EDU 
Pascal Haible, haible@izfm.uni-stuttgart.d. 


C hips & Technology driver 
RealTek SVGA driver. 

Video7 SVGA driver. 

16-color VGA server, and XF86Config parser. 

Hercules driver. 

Banked monochromeVGA support, Hercules support, and 
mono frame buffer support for dumb monochrome devices, 
and many more people out there on the Net who helped with beta-testing this enhancement. 
xFree86 source is available from the FTP server ftp.xFree86.org, among others Send e-mail to xFree86@xFree86.org for 
details. 
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xfs 

xf s— X font server 

SYNOPSIS 

xfs [-config configurationfiIe ] [-port t cppor t ] 


DESCRIPTION 

xfs istheX Window System font server. It supplies fonts to X Window System display servers 


STARTING THE SERVER 

The server isusually run by a system administrator, and started via boot files like /etc/rc. local. Users may also wish to start 
private font servers for specific sets of fonts. 


OPTIONS 

-config configuration_file 
-Is listen-socket 


-port tcp_port 


Specifies the configuration file the font server will use. 

Specifies a file descriptor that is already set up to be used as the 
listen socket. Thisoption is only intended to be used by the 
font server itself when automatically spawning another copy of 
itself to handle additional connections 
Specifies the TCP port number on which the server will listen 
for connections. 


SIGNALS 

SIGTERM 

SIGUSR1 

SIGUSR2 

SIGHUP 


This causes the font server to exit cleanly. 

This signal is used to cause the server to reread its configura¬ 
tion file 

This signal is used to cause the server to flush any cached data 
it may have 

This signal is used to cause the server to reset, closing all active 
connections and rereading the configuration file. 
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CONFIGURATION 


The configuration language is a list of keyword and value pairs. Each keyword isfollowed by an = and then the desired value. 


Recognized keywords include the following: 
catalogue (list of String) 

alternate-servers (list Of String) 
client-limit (cardinal) 

cione-seif (Boolean) 
default-point-size 

(cardinal) 

default - resolutions 

(list of resolutions) 


error-file (String) 

port (cardinal) 
use-sysiog (Boolean) 

deferglyphs (String) 


Ordered list of font path element names U se of the key-word 
"catalogue" is very misleading at present; the current 
implementation only supports a single catalogue (an), 
containing all of the specified fonts 
List of alternate servers for thisfont server. 

N umber of clients thisfont server will support before refusing 
service. This is useful for tuning the load on each individual 
font server. 

W hether thisfont server should attempt to clone itself when it 
reaches the client-limit. 

The default pointsizefin decipoints) for 
fonts that don't specify. The default is 120 . 

Resolutionsthe server supports by default. 

This information may be used asahintfor 
prerendering, and substituted for scaled fonts that do not 
specify a resolution. A resolution isa comma- 
separated pair of x and y resolutions in pixels 
perinch. M ultiple resolutions are separated by commas. 
Filename of theerror file. All warnings and errors will be 
logged here. 

TCP port on which the server will listen for connections 
W hether sysiog(3) (on supported systems) is to be used for 
errors 

Set the mode for delayed fetching and caching of glyphs Value 
is none, meaning deferred glyphsisdisabled, an, meaning it is 
enabled for all fonts and ie, meaning it isenabled only for 16- 
bits fonts 


EXAMPLE 

# sample font server configuration file 

# allow a max of 10 clients to connect to this font server client-limit = 10 

# when a font server reaches its limit, start up a new one clone-self = on 

# alternate font servers for clients to use alternate-servers = hansen:7101,hansen:7102 

# where to look for fonts 

# the first is a set of Speedo outlines, the second is a set of 

# misc bitmaps and the last is a set of 100dpi bitmaps 

catalogue = /usr/X11R6/lib/X11/fonts/speedo, 

/usr/X11R6/lib/XI1/fonts/misc, 

/usr/X11R6/lib/XI1/fonts/100dpi/ 

# in 12 points, decipoints 
default-point-size = 120 

# 100 x 100 and 75 x 75 

default-resolutions = 100,100,75,75 
use-syslog = off 



FONT SERVER NAMES 

One of the following forms can be used to name a font server that acceptsTCP connections 

tcp/h:<f$:{4ame: port tcp/host name: port /c a t a I oguel i st 

The host name specifies the name (or decimal numeric address) of the machine on which the font server is running. Theport 
is the decimal TCP port on which thefont server is listening for connections. Thecat ai oguel i st specifies a list of catalogue 
names, with + as a separator. 

Examples tcp/fs.x.org:7100, tcp/18.30.0.212:7101/all. 

One of the following forms can be used to name a font server that accepts D EC ndt connections 

decnet/nodename: :font$obj name decnet/nodename: :font$obj name /catal oguel i st 

Thenodename specifies the name (or decimal numeric address) of the machine on which thefont server is running. The 
rtjtMme is a normal, case-in sensitive DEC net object name. Thecatai oguel i st specifies a list of catalogue names with + as a 
separator. 

Examples DECnet/SRVNOD: :FONT$DEFAULT, decnet/44.70: :font$special/symbols. 

SEE ALSO 

x(l), font server implementation overview 

BUGS 

M ultiple catalogues should be supported. 

AUTHORS 

DaveLemke (Network Computing Devices, Inc.), Keith Packard (M assachusetts Institute of Technology) 

X Version 11 Release 6 


xhost 

xhost — Server access control program for X 

SYNOPSIS 

xhost [[+-] name ...] 

DESCRIPTION 

The xhost program is used to add and delete hostnames or usernames to the list allowed to make connections to the X server. 
I n the case of hosts, this provides a rudimentary form of privacy control and security. It is only sufficient for a workstation 
(single user) environment, although it doeslimit the worst abuses. Environments that require more sophisticated measures 
should implement the user-based mechanism or use the hooks in the protocol for passing other authentication data to the 
server. 


OPTIONS 


xhost accepts thefollowing command-line options. For security, theoptionsthat effect access control may only be run from 
the "controlling host." For workstations, this isthe same machineas the server. For X terminals, it isthe login host. 


-help Prints a usage message 

[+ 1 n a me Thegivenname (the plus sign is optional) is added to the list 

allowed to connect to the X server. T he name can be a 
hostname or a username. 
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The given name is removed from the list allowed to connect to 
the server. The name can be a hostname or a username 
Existing connections are not broken, but new connection 
attempts will be denied. Note that the current machineis 
allowed to be removed; however, further connections 
(including attempts to add it back) will not be permitted. 
Resetting the server (thereby breaking all connections) isthe 
only way to allow local connectionsagain. 

Access is granted to everyone, even if they aren't on the list (in 
other words, access control isturned off). 

Access is restricted to only those on the list (that is, access 
control isturned on). 

If no command-line arguments are given, a message i ndicating 
whether or not access control is currently enabled is printed, 
followed by the list of those allowed to connect. This isthe 
only option that may be used from machines other than the 
controlling host. 


NAMES 

A complete name has the syntax; a 


name wherethefamiliesareasfollows: 


inet Internet host 

dne DEC net host 

nis Secure RPC network name 

krb KerberosV5 principal 

local Contains only one name, the empty string 

T he family is case insensitive T he format of the name varies with the fami ly. 

When Secure RPC is being used, the network-independent netname (for example, nis:unix.uid@domainname) can be 
specified, or a local user can be specified with just the username and a trailing at sign (@) (for example, ms:pat@). 

For backward compatibility with pre-R6 xhost, names that contain an at sign are assumed to be in the ms family. Otherwise 
the inet family is assumed. 


For each name added to the access control list, a line of the form m 
each name removed from the access control list, a line of theform i 


SEE ALSO 

X(l), Xsecurity(l), Xserver(l), xdm(l) 


To get the default host and display to use 


BUGS 

You can’t specify a display on the command line because -display isavalid command-line argument (indicating that you 
want to remove the machine named display from the access list). 



xieperf 


TheX server stores network addresses, not hostnames. T his is not really a bug. If somehow you change a host's network 
address while the server is still running, xhost must be used to add the new address and/or remove the old address. 

AUTHORS 

Bob Scheifler (M IT Laboratory for Computer Science) andjim Gdttys(M IT Project Athena/D EC) 

X Version 11 Release 6 


xieperf 

xieperf — XIE server extension test and demo program 

SYNTAX 

xieperf [-option ...] 

DESCRIPTION 

The xieperf program isbased upon rs xiiperf(l) , and while not entirely comprehensive in itscoverageof thexiE protocol 
(seethe "Bugs" subsection), it is intended to be useful in the evaluation of xie implementations in the areas of protocol 
adherence and performance The xieperf program includes tests that execute each of the protocol requests and photoflo 
elements specified by revision 5.0 of thexiE protocol. In addition, xieperf provides a set of tests that can be used to validate 
the detection and transmission of xie protocol request errors, such asFloM atch, FloValue, and so forth. Finally, xieperf 
provides a customizable demonstration program for xie. 

A test is made up of three components executed in sequence: an initialization function, a test function, and an end function. 
The initialization function is responsible for allocating and populating test resources, such as photomaps and LUT s, and for 
creating a stored photoflo that will be executed by the test function. The test function, in most cases, simply executes the 
stored photoflo for a specified number of repetitions The end function, which is called following thetest function, is used 
primarily to destroy any noncacheable server resources used by thetest, and to free any memory that was dynamically 
allocated by the client. Sometests, such as -modifyi, -await, -abort, and -redefine, perform additional steps within thetest 
function inner loop, as required bytheelement being tested, or in an attempt to make the test more visually appealing. 
Evaluating the performance of individual xie elements is not as simple as measuring C ore X drawing times T he xie protocol 
requires elements to be embedded within photoflosin order to be exercised, and the minimum possible photoflo sizeistwo. 
This implies that it isimpossibleto measure performance of a single element in isolation— thetime it takes to run theflo 
depends on what other elementsexist in theflo. Extrapolating performance of a single element (or technique) in aflo must 
be done carefully, on a case-by-case basis, becausein general, measured element performance depends on input image size, 
datatype, and other factors all of which can be influenced by upstream flo elements. N ote further that the number and type 
of elements in aflo can be influenced by the visuals available on the display, so even flo-flo comparisons on machines with 
different visuals must be done with caution. 

M any test labelscontain an abbreviated pipeline description. For instance, ip/il/p/ed indicates importPhotomap, importLUT, 
Point, and ExportDrawabie. Pipelinesending in ed (ExportDrawabie) often include hidden elements such asBandExtract, 
convertToindex, Dither, or Point to match theflo output to the screen visual. Pipelinesending in ep (ExportPhotomap) will 
result in a blank window. 

xieperf is compatible with xiiperfcomp(l), which is used to compare the outputs of different xieperf and xiiperf runs in a 
nice tabular format. In xieperf you will need to use the -labels option (seethe "Options" subsection), and provide the 
resulting labelsfileto xiiperfcomp(l) to obtain correct output. See the xiiperf comp(l) man pages for moredetailson this 
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OPTIONS 

xieperf accepts thefollowing options: 
-display hostidpy 
-images <path> 




-script <fiIe > 


-depth <dept h> 

-Grayscale 

-Pseudocolor 

-StaticGray 

-StaticColor 

-TrueColor 

-DirectColor 

-WMSafe 


Specifies which display to use 
N ormally, xiepert references image files located in the 
directory images, which xieperf assumes is located in your 
current directory. If the images directory is not in your current 
directory, or the file has been renamed, use this option to 
specify its location. 

Sometests require the reception of an event such asFioNotify 
to continue and may cause xieperf to hang should these 
events not be received. This option allows the user to specify a 
time-out value which, if exceeded, will cause xieperf to give 
up waiting for an event, and continue on with the next test in 
sequence. Should an event time-out, a warning message will be 
printed to stderr. The default time-out value is 60 seconds. 
Runs the tests in synchronous mode 
U sing this option gives the user the ability to run a subset of 
the available tests and control the number of times the tests are 
executed on an individual basis This is thought to be 
especially useful for those running xieperf for demonstration 
purposes. Using thisoption causes xieperf to read commands 
specified in a script file, or from stdin if <fi/e>is -. Testsare 
specified by newline-terminated input lines of theform 
command [-reps n ] [ -repeat m ]. C haracters following and 
including# are treated as comments. Seethe -mkscript option. 
Repeats each test n times (by default each test is run two 
times). Thisoption may be used in script files also, in which 
case the script file -repeat overrides the command-line option. 
Specifies how long in seconds each test should be run (default 
5 seconds). 

Use a visual with <c/qot/i> planes per pixel (default is the 
default visual). 

U se a Grayscale visual (default isthedefault visual). 

Use a Pseudocolor visual (default isthedefault visual). 

U se a StaticGray visual (default is the default visual). 

U se a staticcoior visual (default isthedefault visual). 

U se a TrueColor visual (default isthedefault visual). 

U se a DirectColor visual (default isthedefault visual). 

If xieperf must be run in a window manager environment, use 
thisflagto make xieperf aware of this. If specified, xieperf 
will create a window, identical to the size of the root window, 
and all further windows created by xieperf will be transient 
pop-up children of this window. If thisflag isomitted, xieperf 
will set the override_redirect attribute Of all windows to True 
and will also do evil things such as calling xinstaiicoiormap. 
Using this option will cause the window manager to (hope¬ 
fully) obey window geometry hints specified by xieperf. 



xieperf 




showtechs 


D isplay a comprehensive list of techniques, by category, 
indicating which of the techniques are supported by thexiE 


showlabels 




errors 

loCal 


all 


mkscript 


labels 


DIS 


range <test1>[,<test2>] 


Print test label to screen prior to calling any of the test code 
This allows the user to know which test is executing in case the 
test hangs for some reason. 

Be verbose when running event and error tests. Also, can be 
used to catch and display information on any signals received 
during execution of xieperf. N otethat thisflag is best used in 
a debugging situation, or to validate that the error events 
recaved by xieperf are valid thefirst timethe tests are 
executed on a new platform. 

Run tests that test for event generation. 

Run tests that test for error event generation. 

Skip test calibration. This may be used when running xieperf 
in situations where execution timing is not important. 
Execution times will not be reported by xieperf when this 
option is enabled. The inner loop repeat count, additionally, is 
set to a value of 5 (but can be overridden by the -reps option). 
Runs all tests This may takeawhile depending on the speed 
of your machine and its floating-point capabilities This 
option isignored if a script file is used. 

G enerate a list of the available tests for the xieperf program. 

In xiiperf, this list is normally displayed in the usage 
statement. 11 was yanked from the usage of xieperf because it 
was too lengthy. 

Generate a script file suitablefor use with the script option. If 
-repeat or - reps are also specified, they will be automatically 
placed attheend of each command in the script. The script is 
generated to stderr. Seethe -script command, above. 

M ost test flos utilize a photomap resource for a source A 
photomap cache of up to n entries iscontrolled by xieperf to 
avoid having to constantly reload these images during test 
initialization. The default cache size is4. If a value less than the 
default is specified, the cache size will be set to the default. 
Generates just the descriptive labels for each test specified. Use 
-an or -range to specify which tests are included. See 
xiiperfcomp(l) for more details 

Pretend we are running xieperf while connected to a Dis-only 
capable implementation of xie. T hiswill cause xieperf to 
executethose tests that only use protocol requests found in the 
dis subset of xie, and bypass those which are not dis- 
compatible If xieperf detects a dis server, it will do this 
automatically, and this option isignored. Use -aiior -range to 
specify the initial range of tests 
Runs all the tests starting from the specified nametesU until 
the name test2, including both the specified tests. Some tests 
like the event and error tests, also require the -errors or - 
events optionsto specified. This option isignored if a script is 
used. 
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-reps <n> Fix the inner loop repetitions to n . This indicates how many 

times the photoflo will be executed each timethetest is run. 
This option is overridden on a per test basis if specified in a 
script. T ypically, xieperf determines the ideal number of reps 
during each test's calibration period. 

-importobscuredEvent Test generation of events. Requires -events flag, 

through -ExportAvailable 


-Badvaiue through Test generation of errors. Requires -errors flag. 

-FloValueError 


-ColorList 

-LUT 

-Photomap 

-ROI 

-Photospace 

-Photoflo 

-QueryPhotomap 

-QueryColorList 

-QueryTechniquesDefault 

through -QueryTechniques 

WhiteAdjust 

-QueryPhotoflo 

-PurgeColorList 


-importclientlutl 
-importclientphotol through 
-importclientphoto9 

-importclientroil 
-importclientroi2 
-encodephotol through 
-encodephoto14 


C reate anddestroy ColorList resource test. 
C reate and destroy lut resource test. 

C reate and destroy Photomap resource test. 

C reate and destroy roi resource test. 

C reate and destroy Photospace test. 

C reate and destroy Photoflo test. 

Q uery Photomap resource test. 

Q uery colonist resource test. 

Q uery techniques as specified by test name. 


Q uery Photoflo test. 

Purge colonist test. 

This test creates a photoflo that is started and blocks for data 
provided by Putciientoatao. Instead of sending the data, the 
test uses xieAbort () to stop the photoflo, and then waits for 
the Photof loDone event to be sent by the server. I f the test times 
out waiting for the event, an error message is sent to stderr. 
Thistestcreatesaflo oftheform importciientLUT -> 

ExportLUT, and starts the flo executing, xieperf then forks, and 
thechild process streams the LUT datatotheflo using 
PutciientData, while the parent blocks in xieAwait. If theflo 
successfully finishes, xieAwait will return and theflo state, after 
query, will indicate that it has completed. If xieAwait does not 
complete naturally, or after return from xieAwait theflo is still 
active an error is reported to stderr. N ote on a really slow 
machine, it is possible that xieAwait will return before the flo 
hasa chance to finish. In this case, use the -timeout option to 
increase the timeout for thistest. 

ImportciientLUT -> ExportLUT test. 

FlOSOf theform ImportClient-Photo -> ExportPhotomap Using 
various decode techniques, for example, G32D, tiff 2 , 

UncompressedTriple. 
importciientROi with 10 rectangles 
importciientROi with 100 rectangles. 

Flosof theform ImportPhotomap - ExportPhotomap Using 
various encode techniques, for example G32D, tiff 2, 
UncompressedTriple. 0 riginal encoding isshown in left 
window; image after encoding isshown in right window. 




-encodeclientphotol through 
-encodeclientphotol1 


-exportclientlutl 

-exportclientroil 


-exportclientroi2 

-exportclienthistograml 

through 

-exportclienthistogram4 

-exportclienthistogramroil 

through 

-exportclienthistogramroi4 

-exportclienthistogramcplanel 

through 

-exportclienthistogramcplane4 

-importlutl 

-importphotol 

-importphoto2 

-importroil 

-importroi2 

-importdrawablel 

-importdrawable2 

-importdrawable3 

-importdrawable4 

-importdrawable5 

-importdrawable6 

-importdrawable7 

-importdrawable8 

-constrainl 


Twoflos, oneoftheform ImportPhotomap ■> 
ExportciientPhoto, and the other of the form 
ImportClientPhoto -> ExportPhotomap, Where 
ExportciientPhoto in thefirst flo uses various encode 
techniques, for example g32d,tiff 2, uncompressedTrtpie. The 
image before encoding is displayed in the left window, while 
the right window shows the image that was encoded in the 
first flo and read back in the second flo. 

ExportciientLUT test. LUT is displayed in a histogram window. 
ExportciientROi test, 10 RO Is. T he ROI sthat are sent to the 
server are represented by the filled rectangles. T he RO I s that 
are received back from the server by the client are drawn as 
white-bordered, nonfilled rectangles The resulting output 
illustrates how the server combined the rectangles sent to it. 
Same as exportclientroil, except using 100 rectangles 
ExportciientHistogram tests using various images The 
histogram isdisplayed in a window that overlaps the image. 

Same as the ExportciientHistogram test, but using a RO I 
to identify the area of i nterest. 

Same as the ExportciientHistogram test, but using a 
control plane to identify the area of interest. 

Test importLUT element; LUT size is 256. 

ImportPhotomap -> ExportPhotomap, With Source and destina¬ 
tion equal. 

ImportPhotomap -> ExportDrawable, window destination. 
importROi -> ExportROi, 10 rectangles, source and destination 
ROIsequal. 

importROi -> ExportROi, 100 rectangles, source and destination 
ROIsequal. 

ImportDrawable -> ExportDrawable, Source ispixmap, 
destination is window. 

ImportDrawable -> ExportDrawable, source and destination are 
both window. 

ImportDrawable -> ExportDrawable, destination window 
obscured by source window. 

ImportDrawable -> ExportDrawable, SOUrcewindOW Obscured 
by destination window. 

ImportDrawablePlane -> ExportDrawablePlane, pixmap, Source 
=desti nation. 

ImportDrawablePlane -> ExportDrawablePlane, window, Source 
=desti nation. 

ImportDrawablePlane -> ExportDrawablePlane, window, Source 
obscures destination. 

ImportDrawablePlane -> ExportDrawablePlane, window, 

destination obscures source 

Constrain Hardcup technique test, drawable destination. 
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-constrain2 

-constrainphotol 

-constrainphoto2 

-convolvel 

-convolve2 

-convolve3 

-convolve4 

-convolveroil 

-convolveroi2 

-convolvecplanel 

-convolvecplane2 

-mathl through -mathcplane7 

-arithmeticdyadicl through 
-arithmetlcdyadic5 
-anithmeticmonadicl through 
-arithmeticmonadic9 
-anithmeticdyadicroil 
through 

arithmeticdyadicroi5 

-arithmeticmonadicroil 

through 

-arithmeticmonadicroi9 

-arlthmeticdyadiccplanel 

through 

-anlthmeticdyadiccplane5 

-arithmeticmonadiccplanel 

through 

-arithmeticmonadiccplane9 

-arithmetlcfloatdyadicl 

though 

-arithmeticfloatdyadicS 

-anlthmeticfloatmonadicl 

though 

-anlthmeticfloatinonadic9 

-arithmeticroifloatdyadicl 

to 

-arithmetlcroifloatdyadic5 

-arithmeticroifloatmonadicl 

to 

• rithmeticroifloatmonadlc9 


Constrain cupscaie technique test, drawable destination. 
Constrain Hardciip technique test, photomap destination. 
Constrain ciipScaie technique test, photomap destination. 
Boxcar 3x3 convolution test. Smoothing or lowpassfilter. 
Boxcar 5x5 convolution test. Smoothing or lowpass filter. 
LaPlacian 3x3 convolution test. Edge or high pass filter. 
LaPlacian 5x5 convolution test. Edge or high pass filter. 
LaPlacian 3x3 convolution test, with ROI. 

LaPlacian 5x5 convolution test, with RO I. 

LaPlacian 3x3 convolution test, with control plane 
LaPlacian 5x5 convolution test, with control plane 
Various tests that exercise the math element, some tests using 
ROIsand control planes. 

Arithmetic element tests, using photomaps 
as the operands. 

Arithmetic element tests, photomap and constant operands. 

Arithmetic element tests, using - photomaps asthe 
operands, with RO Is. 

Arithmetic element tests, photomap and 
constant operands, with RO Is. 

Arithmetic element tests, using photomaps as the 
operands, with control planes 

Arithmetic element tests photomap and constant 
operands with control planes 

Arithmetic element tests using photomaps 
asthe operands, unconstrained. 

Arithmetic element tests photomap and constant 
operands unconstrained. 

Arithmetic element tests photomaps asthe 
operands rois, unconstrained. 

Arithmetic element tests photomap and 
constant operands RO Is, unconstrained. 

BandSeiect element test. Image input is triple band. If visual of 
xieperf window is a color visual, then three Band-select 
elements are used to extract the individual bands' they are 
combined once again using BandCombine, and displayed using 
convertToindex. If the visual is not color, for example 
Grayscale or staticGray, then theflo simply usesone 
BandSeiect element to extract a single band for display. 







xieperf 








-comparedyadicl through 
-comparedyadic6 
-comparemonadicl through 
-comparemonadic6 
-compareroidyadicl through 
-compareroidyadic6 
-compareroimonadicl through 
compare compareroimonadic6 
-comparecplanedyadicl 
through 

-comparecplanedyadic6 

-comparecplanemonadicl 

through 

- comparecplanemonadic6 
-matchhistograml 

through 

-matchhistograml 8 

-matchhistogramroil 

through 

-matchhistogramroi6 

-matchhistogramcplanel 

through 

-matchhistogramcplane6 

-unconstrainl 

-pasteupl through -pasteup2 

-geometryl through 

-geometry14 

-geometry15 through 

-geometry28 

-geometry29 through 

-geometry42 

-geomg31dscale1 through 

-geometryfaxradiol 

-ditherl 

-dither2 


BandCombine test. Input bands are made of three separate single 
band photomaps These are combined using a BandCombine 
element, which is followed by aBandExtract and 
ExportDrawabie. CCIR 601-1 coefficients. 

BandExtract test. Input isa triple band photomap. CCIR 
601-1 coefficients. D estination window colormap is gray ramp. 
BandExtract test. Input isa triple band photomap. CCIR 
601-1 coefficients. Destination window colormap is rgb best 
map standard colormap. 

BandExtract test. Input isa triple band photomap. CCIR 
601-1 coefficients. Destination window colormap is 
rgb_default_map standard colormap. 

T est various compare operators with dyadic 
photomap operands 

T est various compare operators with photomap, 
constant operands 

T est various compare operators with dyadic photomap 

operands using ROIs 

T est various operators with photomap, 

constant operands using RO Is 

T est various compare operators with dyadic 

photomap operands control planes. 

Test various compare operators with photomap, 
constant operands control planes. 

MatchHistogram element tests, using various 
images and histogram matching techniques 

A selection of MatchHistogram element 
tests with ROIs 

A selection of M atchH istogram element 
tests with control planes. 

ImportPhotomap, Unconstrain, Constrain(ClipScale), 
ExportDrawable test, 
pasteup element tests. 

Geometry element tests including rotations, scales 
and mirroring. NearestNeighbor technique. 

Geometry element tests including rotations, scales 
and mirroring. AntiAiias technique. 

Geometry element tests including rotations, scales 
and mirroring. Btiinearinterpoiation technique. 

T eststo exercise the various FAX decoders and 
the Geometry element. 

Dither test, ErrorDiffusion dither technique ExportDrawable. 
Dither test, ErrorDiffusion dither technique 
ExportDrawablePlane. 
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-logicalmonadicl through 
■logicalmonadic16 
■logicaldyadicl through 
■logicaldyadic16 

licalmonadicroil through 
■logicalmonadicroi16 
■logicaldyadicroil through 
-logicaldyadicroi16 
-logicalmonadiccplanel 
through 

-logicalmonadiccplanel6 

-logicaldyadiccplanel 

through 

-logicaldyadiccplanel6 
-blendl 


-blend2 

-blendroil 


-blendcplanel 

-blendcplane2 

-blendalphal 

-blendalpha2 

-blendalpharoil 

-blendalpharoi2 

-triplepointl through 
-triplepoint2 
-funnyencodel through 
-funnyencode8 


Dither test, 0rdered(4) dither technique, ExportDrawable. 

Dither test, 0rdered(4) dither technique, ExportDrawablePlane. 
Dither test, 0rdered(8) dither technique, ExportDrawable. 

Dither test, 0rdered(8) dither technique, ExportDrawablePlane. 
Dither test, D efault dither techniques ExportDrawable. 

Dither test, D efault dither techniques ExportDrawablePlane. 

Logical element, photomap and a constant 

of 0 as operands, various operators 

Logical element tests, dyadic photomaps as 

operands various operators 

Logical element, photomap and constant of 

0 operands various operators RO Is. 

Logical element, dyadic photomaps as operands, various 
operators RO Is. 

Logical element, photomap and constant of 0 
operands various operators Control Planes 

Logical element, dyadic photomaps as operands, 
various operators control planes 

Biend element test. M onadic source, 0.1 source constant. 

Alpha constant of 0.5. 

Biend element test. D yadic sources Alpha constant of 0.5. 

Biend test. M onadic source, 0.1 source constant. Alpha 
constant of 0.5. ROIs 

Biend element test. D yadic sources Alpha constant of 0.5. 
UsesROIs 

Biend test. M onadic source, 0.1 source constant. Alpha 
constant of 0.5. control plane 
Biend element test. D yadic sources Alpha constant of 0.5. 
control plane 

Biend test. M onadic source, 220 source constant. Alpha plane 
is a photomap. 

Biend test. D yadic sources Alpha plane is a constant 220. 

Biend test. M onadic source, 220 source constant. Alpha plane 
photomap. ROIs 

Biend test. D yadic sources Alpha plane is a constant 220. 

ROIs 

Illustrate use of point and standard colormaps 
for rendering triple band images 
These tests are designed to perform limited exercising of XIE's 
capability of dealing with various encodings of flo source data. 
Thetestinit function obtainsa photomap using icp ■> ep.A 
series of independent permanent flo pairs one of theform ip 
-> ep, and the other of the basic form ip -> ED.arecon- 
structed. The encoding pararndtersfortheExportPhotomap (ep) 
element in the first flo are derived from test configuration. The 
number of flo pairs created isalso dependent upon test 
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pointl through -point3 

pointroil 

pointcplanel 

pointphotol 

pointroiphotol 

pointcplanephotol 

redefine 


modifyl 

modify2 

modify3 

modify4 


modify5 


rgbl through -rgbl6 


converttoindexpixel 

converttoindexplane 


configuration. Thetests can be configured so that the test init 
function will constrain the input photomap to a specified 
number of levels, on a per band basis, so that word-sized and 
quad-sized pixels are passed through theflos. Some tests below 
take advantage of this Seetests.cfor test configuration, and 
hints on how to add similar tests 
Simple Point element tests. Drawable destination. 

Simple Point element test that uses RO Is Drawable destination. 
Simple Point element test that uses a control plane. D rawable 
destination. 

Simple Point element test. Photomap destination. 

Simple Point element test that uses RO Is. Photomap 
destination. 

Simple Point element test that uses a control plane. Photomap 
destination. 

T wo flographs are created that are the same in structure, 
except for the x and y offsets specified for the ExportDrawable 
flo elements. Thetest init function creates a photoflo based 
upon one of the two flographs. The inner loop of thetest 
function usesxieRedefinePhotofioo to alternate between each 
of the flographs. M ake sure that your inner loop reps are 2 or 
greater in order to exercise this test fully (see -reps). 

Test xieModifyPhotof io () by adjusting RO I offsets and size. 

T est xieModifyPhotofio() by changing the LUT input toa 
point element. 

T est XieModif yPhotof lo () by changing ExportDrawable x and y 
offsets 

T his test creates a rather long flo of arithmetic elements, each 
of which does nothing more than add i to asmall image The 
test init function scales the input photomap. T he 
ExportDrawable x and y offset is modified randomly during 
each iteration of the test function inner loop. 

T his test creates a rather long flo of arithmetic elements, each 
of which does nothing more than add i to a large image. Each 
rep, the Geometry and ExportDrawable elements at the end of 
the flo are modified to crop a small piece of the input into its 
appropriate place in the larger image 
These tests all basically take an uncompressedTripie image as 
input, send it to ConvertFromRGB, which converts the image to 
some configured colorspace and then send the converted 
image on to convertToRGB priorto display. Theoriginal image 
is displayed in the left-hand window, and the image that has 
passed through the flo is shown in the right-hand window. 
Thegoal Of these test istO Show that ConvertFromRGB -> 
ConvertToRGB islOSSleSS. 

ConvertToIndex test, TripleBand BandByPixel. 

ConvertToIndex test, TripleBand BandByPlane. 
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-convertfromindex 


-complex 

X DEFAULTS 

There are no X defaults used by this program. 

SEE ALSO 

X(l), xllperf(l), xllperfcomp(l) 

BUGS 

There should bean images environment variable to augmentthe -images option. 

M any testsonly scratch thesurfaceof possible test cases. Some of the options available for certain flo elements are either 
inadequately tested, or ignored altogether. There are insufficient tests for bitonal, large pixel, or triple band tests 
Someof the test names areinconsistently cased, for example, -Abort and -ditheri. 

Sometestsare hopelessly slow when run against machineswith slow FPUs 

Bitonal images are for the most part, displayed using the ExportDrawabie flo element; however, ExportDrawabiePiane would 
be a better choice. 

AUTHOR 

Syd Logan (AGE Logic, Inc.) 

X Version 11 Release6 


The test init function uses a flo containing convertToindex to 
display an image in the left window. The test function uses 
thisdrawable as input to a flo that does convertFromindex -> 
convertToindex and sends the resulting image to the right 
window. The result should be lossless. 

A somewhat large flo that uses control planes LUTs Point, 

Pasteup, Logical, Constrain, Dither, Geometry, MatchHistogram, 

BandCombine, and Bandseiect elements. See the Postscript file 
compiex.ps for a rendition of the photoflo that is executed. 


ximtoppm 

ximtoppm— Convertan xim file into a portable pixmap 

SYNOPSIS 

ximtoppm [xi mf i I e] 

DESCRIPTION 

Reads an xim file as input. Produces a portable pixmap as output. Thexim toolkit is included in thecontrib tree of the 
X.V11R4 release 

SEE ALSO 

ppm(5) 

AUTHOR 

Copyright (c) 1991 byjef Poskanzer. 


25 March 1990 
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xinetd 

xinetd— The extended Internet services daemon 

SYNOPSIS 


DESCRIPTION 

xinetd performs the same function astnetd: it starts programsthat provide Internet services. Instead of having such servers 
started at system initialization time and be dormant until a connection request arrives, xinetd is the only daemon process 
started and it listens on all service ports for the services listed in its configuration file. When a request comes in, xinetd starts 
the appropriate server. Because of the way it operates, xinetd (as well as tnetd) is also referred to as a super-server. 

The services listed in xinetd's configuration file can be separated into two groups. Services in thefirst group are called 
multithreaded and they require theforking of a new server processfor each new connection request. The new server then 
handles that connection. For such services, xinetd keeps listening for new requests so that it can spawn new servers On the 
other hand, the second group includes services for which the service daemon is responsible for handling all new connection 
requests Such services are cal led single-threaded and xinetd will stop handling new requests for them until the server dies 
Services in this group are usually datagram based. 

So far, the only reason for the existence of a super-server was to conserve system resources by avoiding to fork a lot of 
processes who might be dormant for most of their lifetime. While fulfilling this function, xinetd takes advantage of the idea 
of a super-server to providefeaturessuch as access control and logging. Furthermore, xinetd is not limited to services listed in 
/etc/services. Therefore, anybody can use xinetd to start special-purpose servers 


OPTIONS 


-syslog syslog_fa 


-f config_file 






Enables debug mode. This produces a lot of debugging 
output, and it makes it possible to use a debugger on xinetd. 
This option enables sysiog logging of xinetd-produced 
messages using the specified sysiog facility. Thefollowing 
facility names are supported: daemon, auth, user, iocai[e-7] 
(check sysiog. cont (5) for their meanings). This option is 
ineffective in debug mode because all relevant messages are 
sent to the terminal. 

xinetd-produced messages will be placed in the specified file 
M essages are always appended to the file If the file does not 
exist, itwill be created. This option is ineffective in debug 
mode because all relevant messages are sent to the terminal. 

D etermi nes the fi le that xinetd uses for configurati on. The 
default is/etc/xinetd-conf. 

The process pid is written to standard error. This option is 
ineffective in debug mode 

This option sets the loop rate beyond which a service is 
considered in error and is deactivated. The loop rate is 
specified in terms of the number of servers per second that can 
be forked for a process The speed of your machine determines 
thecorrectvalueforthisoption. The default rate is 10 . 

If this option is used, xinetd will set the socket option 
so_reuseaddr before binding the service socket to an Internet 
address Thisallowsbinding of the address even if there are 
programsthat use it, which happens when a previous instance 
of xinetd has started some servers that are still running. This 
option hasno effect on RPC services 
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-limit proc.iimit T his option places a limit on the number of concurrently 

running processes that can be started by xinetd. Its purpose is 
to prevent process table overflows. 

-logprocs limit T his option places a limit on the number of concurrently 

running servers for remote user ID acquisition. 

-shutdownprocs i i mi t This option placesa limit on the number of concurrently 

running servers for service shutdown (forked when the record 
option is used). 

T he sysiog and f iieiog options are mutually exclusive. If none isspecified, the default is sysiog using the daemon facility. 
You should not confuse xinetd messages with messages related to service logging. The latter are logged only if this is specified 
via the configuration file. 

CONFIGURATION FILE 

The configuration file determines the services provided by xinetd. Any line whose first nonwhitespace character isa# is 
considered a comment line. Empty lines are ignored. 

Thefile contains entries of theform: 

service <service_name> 
it 

<attribute> <assign_op><value><value> ... 


The assignment operator, assign_op, can be one of =, +=, -=. The majority of attributes support only the simple assignment 
operator, =. Attributes whose value is a set of values support all assignment operators. For such attributes, += means adding a 
value to the set and -= means removing a value from the set. A list of these attributes is given after all the attributes are 
described. 

Each entry definesa service identified bytheservice_name.Thefollowingisalistof available attributes: 
id This attribute is used to uniquely identify a service. This is 

useful because there exist services that can use different 
protocolsand need to be described with different entries in the 
configuration file. By default, theserviceid is the same as the 
service name 

type Possible values are the following: 

rpc If this is an rpc service 

internal If this is a service provided by xinetd. 

unlisted If this is a service not listed in /etc/services, 

flags Possible flag values are 

reuse set the so_reuseaddr flag on the service socket. 

intercept I ntercept packets or accepted connections in 
order to verify that they are coming from 
acceptable locations (internal or multithreaded 
services cannot be intercepted). 
noretry Avoid retry attempts in case of fork failure, 
socket type Possible values are 

stream Stream-based service 

dgram D atagram-based service 

raw Servicethatrequiresdirectaccessto IP 

seqpacket Servicethat requi res rel iable sequenti al 

datagram transmission 



protocol 




instances 


only_from 


Determines the protocol that is employed by theservica The 
protocol must exist in /etc/protocois. If this attribute is not 
defined, the default protocol employed by the service will be 
used. 

This attribute determines if the service is si ngle-threaded or 
multithreaded. If its value is yes, the service is single-threaded; 
thismeansthatxinetd will start the server and then it will stop 
handling requests for the service until the server dies If the 
attribute value is no, the service is multithreaded and xinetd 
will keep handling new service requests. 

D etermi nes the uid for the server process. T he username must 
exist in /etc/passwd. This attribute is ineffective if the effective 
user ID of xinetd is not super-user. 

D etermi nes the gid for the server process. The group name 
must exist in /etc/group. If a group is not specified, the group 
of user will beused (from /etc/passwd). Thisattribute is 
ineffective if the effective user I D of xinetd is not super-user. 

D etermi nes the number of servers that can be si multaneously 
active for a service. By default, there is no limit. T he value of 
this attribute can be either a number or unlimited, which 
means that there is no limit. 

D eterminesthe program to execute for thisservice 
D etermi nes the arguments passed to the server. I n contrast to 
inetd, the server name should not be included in server_args. 
Determines the remote hosts to which the particular service is 
available. Its value is a list of IP addresses that can be specified 
in any combination of the following ways: 

a) A numeric address in theform of %d .%d M .%d. If the 
rightmost components areo, they are treated as wildcards 
(for example, 128 . 138 . 12.0 matches all hosts on the 
i28.i38.i2 subnet). 0 . 0 . 0.0 matchesall Internet addresses 

b) A factorized addressin theform of %d .%d .%d .{%d ,%d 
T here is no need for all four components 

(%d.%d.{%d,%d,...%d} isalsoOK). However, thefactorized 
part must be at the end of the address. 

c) A network name (from /etc/networks). 

d) A hostname. All IP addresses of the specified hostname will 
beused. 

Specifying this attribute without a value makes the service 
available to nobody. 

D eterminesthe remote hosts to which the particular service is 
unavailable Its value can be specified in the same way as the 
value of the only from attribute These two attributes 
determine the location access control enforced by xinetd. If 
none of the two is specified for a service the service is available 
to anyone If both are specified for a service, the one that is the 
better match for the address of the remote host determines if 
the service is avail able to that host (for example if the only 
from list contains 128.138. 209.0 and the no access list contains 
i28.i38.209.i0, then the host with the address 128 . 138 . 209.10 
can not access the service). 
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Determine the time intervals when the service is available An 
interval hastheform hour: mi n-hour: mi n (connectionswill be 
accepted at the bounds of an interval). H ours can range from 0 
to 23 and minute from 0 to 59. 

D etermi ne where the service log output is sent. T here are two 
formats: 

SYSLOG syslog T he log output is sent to syslog at 
facility the specified facility. If a level 
[syslog level] is present, the message will berecorded at 
that level instead of log_info (which isthe 
default level). 

file f i i e T he log output is appended to f i i e, 
[soft_iimit which will be created if it doe 
[hard_iimit] ] not exist. T wo limits on the size of the log 
file can be optionally specified. Thefirst 
limit isa soft one; xinetd will log a message 
the first time this limit is exceeded (if xinetd 
logs to syslog, the message will be sent at 
the log_alert priority level). The second 
limit isa hard limit; xinetd will stop logging 
for the affected service (if the log file is a 
common log file then more than one service 
may be affected) and will log a message 
about this (if xinetd logs to syslog, the 
message will be sent at the log_alert priority 
level). If a hard limit is not specified, it 
defaults to the soft limit increased by 1 
percent but the extra size must be within the 
parameters log_extra_min and log_extra_max 
(defined in config.h). 

Determines what information islogged when aserver i s started 
and when that server exits (the service ID is always included in 
the log entry). Any combination of the following values may 
be specified: 

pid Logsthe server process ID. (If the service is 

implemented by xinetd without forking another 
process the logged process ID will bee.) 
host Logsthe remote host address 

time Logsthetimewhentheserverwasstarted. 

userid Logstheuser ID of the remote user using the 

RFC 931 identification protocol. This option is 
available only for multithreaded stream services 
exit Logsthefact that a server exited along with the 

exit status or the termination signal (the process 
ID is also logged if the pid option is used). 
duration Logstheduration of a service session. 

Determines what information islogged when a server cannot 
be started (either because of a lack of resources or because of 
access control restrictions). The service ID is always included 
in the log entry along with the reason for failure. Any 
combination of thefollowing values may be specified: 
host Logsthe remote host address 
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time Logsthetimewhen theserver wasstarted. 

userid LogstheuserID oftheremoteuserusingtheRFC 

931 identification protocol. This option is available 
only for multithreaded stream services 
attempt Logsthefactthat afailed attempt wasmade 

record Records information from the remote end in case 

theserver could not be started. Thisallows 
monitoring of attempts to use the service. For 
example, the login service logs the local user, 
remote user, and terminal type Currently, the 
services that support this option areiogiun, shell, 
exec, finger. 

Determines the RPC version for an RPC service. The version 
can bea single number or a range in theform number- 
number. 

T he value of this attribute is a list of strings of the form 
name=vaiue. These strings will be added to the environment 
before starting a server (therefore the server's environment will 
include xinetd's environment plus the specified strings). 

The value of this attribute is a list of environment variables 
from xinetd's environment that will be passed to theserver. 

D etermi nes the service port. If this attribute is specified for a 
service listed in /etc/services, it must be equal to the port 
number listed in that file. 

You don't need to specify all of the preceding attributes for each service T he necessary attributes for a service are the 
following: 

(non-unlisted servicesonly) 

(non-internal servicesonly) 

(RPC and unlisted servicesonly) 

(RPC servicesonly) 

(unlisted servicesonly) 

Thefollowing attributes support all assignment operators, except as indicated: 


only_from 



env (does not support the -= operator) 

These attributes can also appear more than once in a service entry. The remaining attributes support only the= operator and 
can appear at most once in a service entry. 

The configuration file may also contain a single defaults entry that has the form: 
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This entry provides default attribute values for service entries that don't specify those attributes. Possible default attributes: 


log_type 

log_on_success 

log_on_failure 

only_from 

passenv 


(cumulative effect) 
(cumulative effect) 
(cumulative effect) 
(cumulative effect) 
(cumulative effect) 


disabled (cumulative effect) 

Attri butes with acumulative effect can be specified multi pie times with the values specified each timeaccumulating (in other 
words, = does the same thing as+=)■ With the exception of disabled they all have the same meaning asif they were specified 
in a service entry, disabled determines services that are disabled even if they haveentriesin the configuration file This allows 
for quick reconfiguration by specifying disabled services with the disabled attribute instead of commenting them out. The 
value of this attribute isa list of space-separated service ID s. 

INTERNAL SERVICES 

xinetd provides the following services internally (both stream- and datagram-based): echo, time, daytime, chargen, and 
discard. These services are under thesame access restrictionsasall other services except for the ones that don't require xinetd 
to fork another process for them. Those ones (time, daytime, and the datagram-based echo, chargen, and discard) have no 
limitation in thenumber of instances. 

CONTROLLING xinetd 

xinetd performs certain actions when it receives certain signals. Theactionsassociated with thespecific signalscan be 
redefined byeditingconfig.hand recompiling. 

sigusri Causes a soft reconfiguration, which meansthat xinetd rereads 

the configuration file and adjusts accordingly. 

SIGUSR 2 Causes a hard reconfiguration, which is the same as a soft 

reconfiguration except that serversfor services that are no 
longer available are terminated. Access control is performed 
again on running servers by checking the remote location, 
access times and server instances If the number of server 
instances is lowered, some arbitrarily picked servers will be 
killed to satisfy the limit; thiswill happen after any servers are 
terminated because of failing the remote location or access 
time checks. Also, if the intercept flag was clear and is set, any 
running servers for that service will determinated; the purpose 
of this is to ensure that after a hard reconfiguration there will 
be no running servers that can accept packets from addresses 
that do not meet the access control criteria. 

sigquit C auses program termination. 

sigterm Terminatesall runningserversbeforeterminatingxinetd. 

sighup Causes an internal state dump (the default dump file is /tmp/ 

xinetd. dump; to change the filename, edit contig.h and 
recompile). 

sigiot Causes an internal consistency check to verify that the data 

structures used by the program have not been corrupted. 

When the check is completed xinetd will generate a message 
that says if the check was successful or not. 
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On reconfiguration, the log files are closed and reopened. This allows removal of old log files. Also, thefollowing attributes 
cannot be changed on reconfiguration: socket_type, wait, protocol, type. 

xinetd LOG FORMAT 

Log entries are lines with thefollowing format: 


The data depends on the entry. Possible entry types: 

start G enerated when a server is started 

exit G enerated when a server exits 

fail Generated when it is not possible to start a server 

data G enerated when an attempt to start a server fails and the 

service supports the record log option. 

userid Generated if the userid log option is used. 

In thefollowing formats, the information enclosed in brackets appears if the appropriate log option is used. 

A start entry has the format 

START: service-ill [pid=%d] [f rom=%d. %d. %d. %d ] [time=t i me ] 

Time is given aSyear/month/day@hour:minutes:seconds. 

An exit entry has the format 

EXIT: service-id [type=%d] [pid=%d] [duration=%d(sec)] 

type can be either statusor signal. The number iseither the exit status or the signal that caused process termination. 

A FAIL entry hastheformat: 

FAIL: service-id reason [from=%d.%d.%d.%d] [time=t i me] 


Possible reasons are 

fork 

time 

address 

service_limit 

process_limit 


A certain number of consecutivefork attempts failed (this 
number is a configurable parameter). 

Thetimecheck failed. 

T he address check failed. 

The allowed number of server instances for this service would 
be exceeded. 

A limit on thenumber of forked processes was specified and it 
would be exceeded. 


A data entry hastheformat 

DATA: service-id data 


The dat a logged depends on the service. 

login remote_user=%s local_user=%s tty=%s 

exec remote_user=%s verify=status command=%s Possible status 

values: 

ok The password was correct 

failed The password was incorrect 

baduser N o such user 

shell remote_user=%s local_user=%s command=%s 

finger received string Of EMPTY-LINE 
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A userid entry has the format 

USERID: text 

Thet ext isthe response of the RFC 931 daemon at the remote end excluding the port numbers (which are included in the 
response). H ere'san example 

# Sample configuration file for xlnetd 
defaults 

log_type = FILE /var/log/servicelog 
log_on_success = PID 
log_on_failure = HOST TIME RECORD 

only_from = 128.138.193.0 128.138.204.0 128.138.209.0 
only_from = 128.138.252.1 

disabled = rstatd 


# Note 1: the protocol attribute is not required 

# Note 2: the instances attribute overrides the default 

service login 

| 

socket_type = stream 
protocol = tcp 


server = /usr/etc/in.rlogind 
instances = UNLIMITED 


# Note 1: the instances attribute overrides the default 

# Note 2: the log on success flags are augmented 

service shell 

I 

socket_type = stream 

user = root 
instances = UNLIMITED 
server = /usr/etc/in.rshd 
log_on_success += HOST TIME RECORD 

} 

service ftp 

socket_type = stream 


server = /usr/etc/in.ftpd 
server_args = -1 

log_on_success += DURATION HOST USERID 
access_times = 2:00-9:00 12:00-24:00 


# This entry and the next one specify internal services. Since this 

# is the same service using a different socket type, the id attribute 

# is used to uniquely identify each entry 
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service echo 


type = INTERNAL 
socket_type = stream 


service echo 


id = echo-dgram 
type = INTERNAL 
socket_type = dgram 


# Sample RPC service 
service rstatd 


type = RPC 
socket_type = dgram 
protocol = udp 

server = /usr/etc/rpc.rstatd 
wait = yes 


rpc_version = 2-4 

env = LD_LIBRARY_PATH=/etc/securelib 


# Sample unlisted service 

{ 

type = UNLISTED 
socket_type = stream 
protocol = top 

server - /home/user/some server 
port = 20020 

} 

FILES 

/etc/xinetd. conf D efault configuration file 

/tmp/xinetd.dump Default dump file 

SEE ALSO 

inetd(8) 

Postel J., Echo Protocol, RFC 862, May 1983. 

Postel J., Disard Protocol, RFC 863, M ay 1983. 

Postel J., Character Generator Protocol, RFC 864, M ay 1983. 

Postel j., Daytime Protocol, RFC 867, M ay 1983. 

Postel J., FI arrenstien K., TimeProtocol, RFC 868, M ay 1983. 

St. JohnsM ., Authentication Server, RFC 931, January 1985. 
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AUTHOR 

PanosTsirigotis (C S D epartment, U niversity of Colorado, Boulder) 

NOTES 

W hen the attributes oniy_f rom and no_access are not specified for a service (either directly or via defaults), the address check 
is considered successful (that is, access will not be denied). 

If the userid log option is specified and the remote RFC 931 server sends back an error reply, access will not be denied. 

If the userid log option is specified and the remote host does not run an RFC 931 server, there will be no indication in the 
log of that fact (other than the missing userid log entry). 

BUGS 

Supplementary group ID s are not supported. 

If the intercept flag is not used, access control on the address of the remote host is not performed when wait is yes and 
socket_type is stream. 

If the intercept flag is not used, access control on the address of the remote host for services where watt is yes and 
socket_type isdgram is performed only on the first packet. The server may then accept packets from hosts not in the access 
control list. Thiscan happen with RPC services 

U nlisted RPC services are not supported; that is, all RPC services must be registered in /etc/rpc. Specifying an RPC service 
by itsRPC program number isnot (yet) possible. 

There is no way to put a space in an environment variable. 

W hen wait is yes and socket_type is stream, thesocket passed to the server can only accept connections. 

The intercept flag is not supported for internal services or multithreaded services 

I nterception works by forking a process that acts as a fi Iter between the remote host(s) and the local server. T his obviously 
has a performance impact which depends on the volume of information exchanged. It is up to you to make the compromise 
between security and performance for each service. 

PRONUNCIATION 

xinetd is pronounced "zy-net-d." 

10 May 1992 


xinit 

xinit— X Window System initializer 

SYNOPSIS 

xinit [[client ] options ][- [ server [[display ] options ] 

DESCRIPTION 

The xinit program is used to start theX Window System server and a first client program on systems that cannot start X 
directly from /etc/init or in environments that use multiple window systems. When thisfirst client exits, xinit will kill the 
X server and then terminate. 

If no specific client program is given on the command line, xinit will look for a file in the user's home directory called 
.xinitrc to run as a shell script to start up client programs If no such file exists, xinit will use the following as a default: 

xterm -geometry +1+1 -n login -display :0 
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If no specific server program isgiven on the command line, xinit will look for a file in the user's home directory called 
.xserverrc to run as a shell script to start up the server. If no such file exists, xinit will use the following as a default: 


N otethat this assumes that there is a program named X in the current search path. H owever, servers are usually named 
xdispiaytype where dispiaytype isthetype of graphics display that isdriven by thisserver. Thesite administrator should, 
therefore, make a link to the appropriate type of server on the machine or create a shell script that runs xinit with the 
appropriate server. 

Note, when using a .xserverrc script be sure to mark the real X server as exec. Failing to do this can make the X server slow 
to start and exit. For example 

exec Xdispiaytype 

An important point isthat programs which are run by xinitrc should be run in the background if they do not exit right 
away, so that they don't prevent other programs from starting up. FI owever, the last long-lived program started (usually a 
window manager or terminal emulator) should be left in theforeground so that the script won't exit (which indicates that 
the user is done and that xinit should exit). 

An alternate client and/or server may be specified on the command line. The desired client program and its arguments 
should be given asthefirst command-line arguments to xinit. T o specify a particular server command line, append two 
dashes (—) to the xinit command line (after any client and arguments) followed by the desired server command. 

Both the client program name and the server program name must begin with a slash (/) or a period (.). Otherwise they are 
treated as arguments to be appended to their respective startup lines. This makes it possible to add arguments (for example 
foreground and background colors) without having to retype the whole command line 

If an explicit server name is not given and thefirst argument following the double dash (-) isa colon followed by a digit, 
xinit will use that number as the display number instead of zero. All remaining arguments are appended to theserver 
command line 

EXAMPLES 

Following are several examples of how command-line arguments in xinit are used: 

This will start up a server named X and run the user's xinitrc, if it exists, or else start an xterm: 

This is how onecould start a specific type of server on an alternate display: 

xinit — /usr/X11R6/bin/Xqdss :1 

This will start up a server named X, and will append the given arguments to the default xterm command (it will ignore 
xinitrc): 

xinit -geometry =80x65+10+10 -fn 8x13 -j -fg white -bg navy 

This will use the command xsun -1 -c to start theserver and will append the arguments -e widgets to the default xterm 
command: 

xinit -e widgets — ./Xsun -1 -c 

T his will start a server named X on display 1 with the arguments -a 2 -ts: 

xinit /usr/ucb/rsh fasthost cpupig -display ws:1 -- :1 -a 2 -t 5 

It will then start a remote shell on the machine fasthost in which it will run the command cpupig, telling it to display back on 
the local workstation. 

Following is a sample xinitrc that starts a clock, starts several terminals, and leaves the window manager running as the 

"last" application. Assuming that the window manager has been configured properly, the user then chooses the Exit menu 

item to shut down X. 

xrdb -load $H0ME/.Xresources 

xsetroot -solid gray & 
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xclock -g 50x50-0+0 -bw 0 & 
xload -g 50x50-50+0 -bw 0 & 
xterm -g 80x24+0+0 & 
xterm -g 80x24+0-0 & 
twin 

Sites that want to create a common startup environment could simply create a default xinitrc that references a site-wide 
startup file: 

#!/bin/sh 

. /usr/local/lib/site.xinitrc 

Another approach is to write a script that starts xinit with a specific shell script. Such scripts are usually named xii, xstart, 
or startx, and are a convenient way to provide a simple interface for novice users: 

#!/bin/sh 

xinit /usr/local/lib/site.xinitrc — /usr/X11R6/bin/X be 

EN VIRO N M EN T VARIABLES 

This variable gets set to the name of the display to which 
clients should connect. 

This variable specifies an init file containing shell commands 
to start up the initial windows. By default, xinitrc in the 
homedirectory will be used. 


Default client script 

Client to run if .xinitrc does not exist 

D efault server script 

Server to run if .xserverre does not exist 


X(l), startx(l), Xserver(l), xterm(l) 

AUTHOR 

Bob Scheifler (M IT Laboratory for Computer Science) 

X Version 11 Release 6 


DISPLAY 

XINITRC 


FILES 



.xserverre 


SEE ALSO 


xkill 

xkiii— Kill a client by itsX resource 

SYNOPSIS 

xkill [-display di spl ayname ] [-id resource] [-button number] [-frame] [-all] 

DESCRIPTION 

xkiii isa utility for forcing theX server to close connections to clients. This program is very dangerous, but is useful for 
aborting programs that have displayed undesired windows on a user's screen. If no resource identifier is given with -id, xkiii 
will display a special cursor as a prompt for the user to select a window to be killed. If a pointer button is pressed over a 
nonroot window, the server will close its connection to the client that created the window. 
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OPTIONS 

-display di s pi ay name 

-button number 

-all 

XDEFAULTS 

Button 

SEE ALSO 


AUTHOR 

Jim Fulton (M IT X Consortium) and DanaChee(Bellcore) 


This option specifies the name of the X server to contact. 

This option specifies the X identifier for the resource whose 
creator isto be aborted. If no resource is specified, xkni will 
display a special cursor with which you should select a window 
to be kill. 

This option specifies the number of pointer button that should 
be used in selecting a window to kill. If the word "any" is 
specified, any button on the pointer may be used. By default, 
the first button in the pointer map (which is usually the 
leftmost button) is used. 

This option indicates that all clients with top-level windows on 
the screen should be killed, xkin will ask you to select the root 
window with each of the currently defined buttonsto give you 
several chances to abort. Use of this option is highly discour¬ 
aged. 

This option indicatesthat xkin should ignore the standard 
conventionsfor finding top-level client windows(which are 
typically nested inside a window manager window), and 
simply believe that you want to kill direct children of the root. 


Specifies a specific pointer button number or the word "any" 
to use when selecting windows 


X Version 11 Release6 


X(l), xwininfo(l), XKillClient and XGetPointerMapping in theXlib ProgrammffSM anual, KillClient in theX Protocol 
Specification 


xlogo 

xiogo- X W indow System logo 

SYNOPSIS 

xlogo [-tool ki topt i on ...] 

DESCRIPTION 

The xiogo program displays the X W indow System logo. 

OPTIONS 

xiogo accepts all of the standard X Toolkit command-line options as well as the following: 

-shape Thisoption indicates that the logo window should beshaped 

rather than rectangular. 
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RESOURCES 

The default width and the default height are each 100 pixels. This program uses the Logo widgdt in the Athena widget set. It 

understands all of the Simple widget resource names and classes as well as: 

foreground (class Foreground) Specifies the color for the logo. The default depends on 

whether reverseVideo isspecified. If reverseVideo isspecified, 
the default is xtDefauitForeground, otherwise the default is 
XtDefaultBackground. 

shapewindow (class shapewindow) Specifies that the window isshaped to theX logo. Thedefault 

is False. 


WIDGETS 

In order to specify resources, it is useful to know the hierarchy of the widgets that compose xiogo. In the following notation, 
indentation indicates hierarchical structure. The widget class nameisgiven first, followed by the widget instance name. 

XLogo xiogo 

Logo xiogo 

ENVIRONMENT 

display To get the default host and display number. 

xenvironment T o get the name of a resource file that overrides the global 

resources stored in the resource_manager property. 

FILES 

<xRoot>/iib/xi i /app -def auits/XLogo Specifies required resources 

SEE ALSO 

X(l), xrdb(l) 

AUTHORS 

OllieJ ones of Apollo Computer and Jim Fulton of the M IT X Consortium wrote the logo graphics routine, based on a 
graphic design by DannyChongand RossChapman of Apollo Computer. 

X Version 11 Release 6 


xlsatoms 

xisatoms— List interned atomsdefined on server 

SYNOPSIS 

xlsatoms [-options ...] 

DESCRIPTION 

xisatoms lists the interned atoms By default, all atomsstartingfrom 1 (the lowest atom value defined by the protocol) are 
listed until unknown atom is found. If an explicit range isgiven, xisatoms will try all atoms in the range, regardless of 
whether or not any are undefined. 



xlsdients 


OPTIONS 

-display dpy 
-format string 


-range [I ow ] - [hi g h ] 


SEE ALSO 

X(l), Xserver(l), xprop(l) 

ENVIRONMENT 

DISPLAY 

AUTHOR 

Jim Fulton (M IT X Consortium) 


This option specifies the X server to which to connect. 

This option specifies a printf-style string used to list each 
atom <vaiue,name> pair, printed in that order (value is an 
unsigned long and name isa char *). xisatoms will supply a 
newline at the end of each line T he default is %id\t%s. 

T his option specifies the range of atom val ues to check. If i ow 
is not given, a value of i isassumed. If hi gh is not given, 
xisatoms will stop at thefirst undefined atom at or abovei ow. 
This option specifies the name of an atom to list. If the atom 
does not exist, a message will be printed on the standard error. 


To get the default host and display to use 


X Version 11 Release6 


xlsclients 

xisciients— List client applications running on a display 

SYNOPSIS 

xlsclients [-display d i spi ay name ] [-a] [-1] [ -m maxcmdlen] 


DESCRIPTION 

xlsclients isa utility for listing information about thedient applications running on a display. It may be used to generate 
scripts representing a snapshot of the user'scurrent session. 


OPTIONS 

-display di spl ayname 


-m maxcmdlen 


This option specifies the X server to contact. 

This option indicates that clients on all screens should be 
listed. By default, only those clients on the default screen are 
listed. 

List in long format, giving the window name, icon name and 
class hints in addition to the machine name and command 
string shown in the default format. 

This option specifies the maximum number of characters in a 
command to print out. The default is 10000. 


ENVIRONMENT 

DISPLAY 


T0 get the default host, display number, and screen. 
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SEE ALSO 

X(l), xwininfo(l), xprop(l) 

AUTHOR 

Jim Fulton (M IT X Consortium) 

X Version 11 Release 6 


xlsfonts 

xisfonts — Server font list displayer for X 

SYNOPSIS 

xlsfonts [-options ...[ [-fn pattern] 

DESCRIPTION 

xisfonts lists the fonts that match the given pattern. The wildcard character* may be used to match any sequence of 
characters (including none), and ? to match any single character. If no pattern is given, * isassumed. 


T he * and ? characters must be quoted to prevent them 

OPTIONS 

-display host:dpy 

-11 

-111 


-C 



being expanded by the shell. 


This option specifies the X server to contact. 

Lists some attributes of thefont on onelinein addition to its 
name 

Lists font propertiesin addition to -I output. 

Lists character metrics in addition to -n output. 

This option indicates that long listings should also print the 
minimum and maximum bounds of each font. 

This option indicates that listings should use multiple 
columns.Thisisthesameas-n 0. 

Thisoption indicates that listings should use a single column. 
Thisisthesameas-n 1. 

Thisoption specifies the width in characters that should be 
used in figuring out how many columnsto print. The default 
is 79. 

Thisoption specifies the number of columnsto use in 
displaying the output. By default, it will attempt to fit as many 
columns of font names into the number of character specified 

by-w width. 

Thisoption indicates that the output should be left unsorted. 
Thisoption indicates that xisfonts should do an openFont 
(and QueryFont, if appropriate) rather than a ListFonts. This is 
useful if ListFonts or ListFontswithinfo fail to list a known 
font (as is the case with some scaled font systems). 

Thisoption specifies the font name pattern to match. 


SEE ALSO 

x(l), xserver(l), xset(l), xfd(l), X Logical Font Description Conventions 



xmag 


ENVIRONMENT 

display To get the default host and display to use 

BUGS 

D oing xisf onts -i can tie up your server for a very long time. T his is really a bug with single-threaded nonpreemptable 
servers, not with this program. 

AUTHOR 

M ark Lillibridge (M IT Project Athena), Jim Fulton (M IT X Consortium), and Phil Karlton (SGI) 

X Version 11 Rdease6 


xmag 

xmag- M agnify parts of the screen 

SYNOPSIS 

xmag [ -mag magf actor ][-source geom 1 [ -t o o I kitoption ...] 

DESCRIPTION 

The xmag program allows you to magnify portionsof an X screen. If no explicit region is specified, a square with the pointer 
in the upper-left corner is displayed indicating the area to be enlarged. The area can be dragged out to the desired size by 
pressing Button 2. After a region has been selected, a window is popped up showing a blown-up version of the region in 
which each pixel in the source image is represented by a small square of the same color. Pressing Button 1 in the enlargement 
window shows the position and RGB value of the pixel under the pointer until the button is released. Typing? or 'C in the 
enlargement window exits the program. The application has five buttons across its top. Close deletes this particular 
magnification instance. Replace brings up the rubber band selector again to select another region for this magnification 
instance. New brings up the rubber band selector to create a new magnification instance Cut puts the magnification image 
into the primary selection. Paste copies the primary selection buffer into xmag. Note that you can cut and paste between xmag 
and the bitmap program. Resizing xmag resizes the magnification area, xmag preserves thecolormap, visual, and window depth 
of the source 

WIDGETS 

xmag usestheX Toolkit and the Athena Widget Set. The magnified image is displayed in the Scale widget. For more 
information, see the Athena Widget Set documentation. Following is the widget structure of the xmag application. Indenta¬ 
tion indicates hierarchical structure. The widget class name isgiven first, followed by the widget instance name. 

Xmag xmag 

RootWindow root 
TopLevelShell xmag 

Paned pane2 

Command close 
Command replace 
Command new 
Command select 
Command paste 
Label xmag label 

Scale scale 

OverrideShell pixShell 
Label pixLabel 
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OPTIONS 

-source geom 


-mag integer 


Thisoption specifies the size and/or location of the source 
region on the screen. By default, a 64x64 square is provided 
for the user to select an area of the screen. 

Thisoption indicates the magnification to be used. The 
default is5. 


AUTHORS 

D aveSternlicht and Davor M atic (M IT X Consortium) 


X Version 11 Release 6 


xmkmf 

xmkmf— C reate a Makefile from an Imakefile 

SYNOPSIS 

xmkmf [-a][topdir [ curdir ]] 


DESCRIPTION 

The xmkmf command isthe normal way to create a Makefile from an imakef lie shipped with third-party software. 

When invoked with no arguments in a directory containing an imakef He, the imake program isrun with arguments 
appropriate for your system (configured into xmkmf when X was built) and generates a Makefile. 

When invoked with the -a option, xmkmf builds the Makefile in the current directory, and then automatically executes make 
Makefiles (in case there are subdirectories), make includes, and make depend for you. This is the normal way to configure 
software that is outsidetheX Consortium build tree. 

If working inside the X Consortium build tree (unlikely unless you are an X developer, and even then thisoption is never 
really used), the topdir argument should be specified as the relative pathname from the current directory to the top of the 
build tree Optionally, curdir may be specified asa relative pathname from the top of the build tree to thecurrent directory. 
It isnecessary to supply curdir if thecurrent directory has subdirectories, or the Makefile will not be able to build the 
subdirectories. If a topdir isgiven, xmkmf assumes nothing is installed on your system and looks for files in the build tree 
instead of using the installed versions. 


SEE ALSO 

imake(l) 


X Verson 11 Release 6 


xmodmap 

xmodmap— Utility for modifying keymaps in X 

SYNOPSIS 

xmodmap [-options ...] [filename] 

DESCRIPTION 

The xmodmap program is used to edit and display the keyboard modifier map and keymap table that are used by client 
applicationsto convert event keycodes into keysyms. It is usually run from the user's session startup script to configure the 
keyboard according to personal tastes. 



OPTIONS 

Thefollowing options may be used with xmodmap: 

xmodmap 

-display display 

Thisoption specifies the host and display to use 


Thisoption indicates that a brief description of the command¬ 
line arguments should be printed on the standard error 
channel. This will be done whenever an unhandled argument 
is given to xmodmap. 

-grammar 

Thisoption indicates that a help message describing the 
expression grammar used in files and with -e expressions 
should be printed on the standard error. 

-verbose 

Thisoption indicates that xmodmap should print logging 
information asit parses its input. 

-quiet 

This option turns off the verbose logging. T his is the default. 

-n 

Thisoption indicates that xmodmap should not change the 


mappings, but should display what it would do, like make(l) 
does when given thisoption. 

This option specifies an expression to be executed. Any 
number of expressions may be specified from the command 
line 


-pk 

Thisoption indicates that the current modifier map should be 
printed on the standard output. 

Thisoption indicates that the current keymap table should be 
printed on the standard output. 

Thisoption indicates that the current keymap table should be 
printed on the standard output in the form of expressions that 
can be fed back to xmodmap. 


Thisoption indicates that the current pointer map should be 
printed on the standard output. 

A lone dash meansthat the standard input should be used as 
the input file 

T hefilename specifies a file containing xi 
directory with a name like .xmodmaprc. 

modmap expressionsto be executed. Thisfile isusually kept in theuser'shome 

EXPRESSION GRAMMAR 


T he xmodmap program reads a list of expressions and parses them all before attempting to execute any of them. This makes it 
possi bleto refer to keysymsthat are being redefined in a natural way without having to worry asmuch about name conflicts. 

keycode NUMBER = KEYSYMNAME ... 

The list of keysyms is assigned to the indicated keycode (which 
may be specified in decimal, hex, or octal and can be 
determined by running the xev program. 

keycode any = KEYSYMNAME ... 

If no existing key has the specified list of keysyms assigned to 
it, a spare key on the keyboard isselected and the keysyms are 
assigned to it. The list of keysyms may be specified in decimal, 
hex, or octal. 

keysym KEYSYMNAME * fSYSYMNAME ... 

The keysymname on the left side is translated into matching 
keycodes used to perform the corresponding set of keycode 
expressions The list of keysym names may be found in the 
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header file <xi i /keysymdet. h (without the xK_pref ix) or the 
keysym database <xRoot>/iib/xi i /xKeysymDB, where <xRoot> 
refers to the root of the X11 install tree. N ote that if the same 
keysym is bound to multiple keys, the expression is executed 
for each matching keycode. 

This removes all entries in the modifier map for the given 
modifier, where valid names are shift, Lock, control, Modi, 
Mod2, Mod3, Mod4, and Mods (casedoes not matter in modifier 
names, although it does matter for all other names). For 
example, clear Lock will remove any keys that were bound to 
the shift lock modifier. 

This adds all keys containing the given keysymstothe 
indicated modifier map. The keysym names are evaluated after 
all input expressions are read to make it easy to write 
expressionsto swap keys. (See the "Examples" subsection). 
This removes all keyscontainingthegiven keysymsfrom the 
indicated modifier map. Unlike add, the keysym names are 
evaluated as the li ne is read i n. T his allows you to remove keys 
from a modifier without having to worry about whether or not 
they have been reassigned. 

pointer =defauit T his sets the pointer map back to its default settings (button 1 

generates a code of 1, button 2 generates a 2, and so on), 
pointer «s number ... Thissetsto pointer map to contain theindicated button 

codes The list always starts with thefirst physical button. 

Linesthat begin with an exclamation point (i) are taken as comments 

If you want to change the binding of a modifier key, you must also remove it from the appropriate modifier map. 

EXAMPLES 

M any pointers are designed such that thefirst button is pressed using the index finger of the right hand. People who are left- 
handed frequently find that it is more comfortable to reverse the button codes that are generated so that the primary button 
ispressed usingtheindex finger of the left hand. This could be done on a 3 button pointer asfollows% xmodmap -e “pointer 

M any applications support the notion of M eta keys (similar to Control keys except that M eta isheld down instead of 
Control). H owever, some servers do not have a M eta keysym in the default keymap table so one needs to be added by hand. 
The following command will attach M eta to theM ultilanguage key (sometimes labeled Compose Character). It also takes 
advantage of the fact that applicationsthat need a M eta key simply need to get the keycode and don't require the keysym to 
be in thefirst column of the keymap table This means that applicationsthat are looking for a M ulti key (including the 
default modifier map) won't notice any change Example: 

% xmodmap -e "keysym Multi_key = Multi_key Meta_L" 

Similarly, some keyboards have an Alt key but no M eta key. In that case the following may be useful: 

% xmodmap -e "keysym Alt L = Meta L Alt L" 

One of the more simple ydt convenient, uses of xmodmap isto set the keyboard's "rubout" key to generate an alternate 
keysym. This frequently involves exchanging Backspace with Delete to be more comfortable to the user. If thettyModes 
resource in xterm isset as well, all terminal emulator windows will use the same key for erasing characters: 

% xmodmap -e "keysym Backspace = Delete" 

% echo "XTerm*ttyModes: erase *?" | xrdb -merge 


clear MODI FI ERNAME 


d MODI FIERNAME = KEYSYMNAME . 


rpmnvp Mnni FI FRNAMF = YFYAYMNIMF 



xmodmap 
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Some keyboards do not automatically generate less than and greater than characters when the comma and period keys are 
shifted. Thiscan be remedied with xmodmap by resetting the bindings for the comma and period with thefollowing scripts: 

! make shift-, be $<$ and shift-, be $>$ 

keysym comma = comma less 
keysym period = period greater 

One of the more irritating differences between keyboards isthe location of the Control and Shift Lock keys. A common use 
of xmodmap isto swap these two keys asfollows 

! Swap Caps_Lock and Control_L 

remove Lock = Caps_Lock 
remove Control = Control_L 
keysym Control_L = Caps_Lock 
keysym Caps_Lock = Control_L 
add Lock = Caps_Lock 
add Control = Control_L 

T he keycode command is useful for assigning the same keysym to multiple keycodes Although unportable it also makes it 
possible to write scripts that can reset the keyboard to a known state. T he following script sdtsthe Backspace key to generate 
Delete (as shown earlier), flushes all existing caps lock bindings, makes the Caps Lock key be a control key, makeFS generate 
Escape, and makes Break/Reset be a shift lock. 

! On the HP, the following keycodes have key caps as listed: 

! 101 Backspace 

! 55 Caps 

! 14 Ctrl 

! 15 Break/Reset 

! 86 Stop 

! 89F5 

keycode 101 = Delete 
keycode 55 = Control_R 

add Control = Control_R 
keycode 89 = Escape 
keycode 15 = Caps_Lock 
add Lock = Caps_Lock 

ENVIRONMENT 

display To gdt default host and display number 

SEE ALSO 

x(l), xev(l), xnb documentation on key and pointer events 

BUGS 

Every time a keycode expression devaluated, theserver generates a MappingNotify event on every client. Thiscan cause some 
thrashing. All of the changes should be batched together and done at once Clients that receive keyboard input and ignore 
MappingNotify events will not notice any changes made to keyboard mappings 

xmodmap should generate add and remove expressions automatically whenever a keycode that isalready bound to a modifier is 
changed. 
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There should be a way to have the remove expression accept keycodesaswell as keysyms for those times when you really mess 
up your mappings 

AUTHOR 

J im Fulton (M IT X Consortium), rewritten from an earlier version by D avid Rosenthal (Sun M icrosystems) 

X Version 11 Release6 


xon 

xon— Start an X program on a remote machine 

SYNOPSIS 

xon remote-host [-access] [-debug] [-name window-name] [-nols] [-screen screen-no] [-user user-name] [command ...] 


DESCRIPTION 

xon runs the specified command (default xterm -is) on the remote machine using rsh, remsh, or rcmd. xon passes the display, 
xauthority, and xuserfilesearchpath environment variables to the remote command. 

When no command isspecified, xon runs xterm -is. It additionally specifies the application name to be xterm-r emote -host 
and the window title to be -firemote-host. 

xon can only work when the remote host will allow you to log in without a password, by having an entry in the .rhosts file 
permitting access. 


OPTIONS 


N ote that the optionsfollow the remote hostname (asthey do with riogin). 


-access 


•debug 


-screen screen-no 


Runs xhost locally to add the remote host to the host access list 
in theX server. This won't work unless xhost isgiven 
permission to modify the access list. 

Normally, xon disconnects the remote process from stdin, 
stdout.and stderrtoeliminatethedaemon processes that 
usually connect them across the network. Specifying the -debug 
option leaves them connected so that error messages from the 
remote execution are sent back to the originating host. 

This specifies a different application name and window title 
for the default command (xterm). 

Normally xon passes the -is option to the remote xterm; this 
option suspends that behavior. 

This changes the screen number of the display variable passed 
to the remote command. 

By default, xon simply uses rsh/remsh/rcmd to connect to the 
remote machine using the same username as on the local 
machine. Thisoption causes xon to specify an alternative 
username This will not work unless you have authorization to 
access the remote account, by placing an appropriate entry in 
the remote user's. rhosts file. 


BUGS 

xon can get easily confused when the remote host, username or various environment variable values contain whitespace 
xon has no way to send the appropriate X authorization information to the remote host. 


X Verson 11 Release 6 



xpmtoppm 

xpmtoppm— Convert an Xll pixmap into a portablepixmap 

SYNOPSIS 

xpmtoppm [xpmf i I e] 

DESCRIPTION 

Reads an Xll pixmap (XPM version 1 or 3) asinput. Producesa portable pixmap asoutput. 

KNOWN BUGS 

The support to XPM version 3 is limited. Comments can only be single lines and there must be for every pixel a default 
color name for a color type visual. 

SEE ALSO 

ppmtoxpm(l), ppm(5) 

XPM M anual byArnaud LeHorsflehorsiainirsa.inria.fr) 

AUTHOR 

Copyright (c) 1991 byjef Poskanzer. 

Upgraded to supportXPM version 3 byArnaud LeHors(iehors@mirsa. inria.fr) 9 April 1991 

16 August 1990 


xprop 

xprop — Property displayer for X 

SYNOPSIS 

xprop [-help] [-grammar] [-id id] [-root] [-name name] [-frame] [-font font] 

[- display d i s p I ay] [-len n] [-notype] [ -fs file] [- remove property-name] 

[-spy] [-f atom format [dformat]]* [format [dformat] atom]* 

SUMMARY 

The xprop utility is for displaying window and font properties in an X server. One window or font is selected using the 
command-line arguments or possibly in the case of a window, by clicking on the desired window. A list of properties is then 
given, possibly with formatting information. 


Print out a summary of command-line options 
Printout a detailed grammar for all command-line options. 
This argument allows the user to select window id on the 
command line rather than using the pointer to select the target 
window. Thisisvery useful in debugging X applications where 
the target window is not mapped to the screen or where the 
use of the pointer might be impossible or interfere with the 
application. 

This argument allowstheuserto specify that the window 
named name is the target window on the command line rather 
than using the pointer to select the target window. 


OPTIONS 

-help 

-grammar 



Parti: User Commands 


678 


-display display 
-len n 
-notype 


-fs file 


-remove property- name 
-spy 


This argument allowstheuserto specify that the properties of 
font font should be displayed. 

This argument specifies that X's root window is the target 
window. This isuseful in situations where the root window is 
completely obscured. 

This argument allows you to specify the server to connect to; 
seex(l). 

Specifies that at most, n bytes of any property should be read 
or displayed. 

Specifies that thetype of each property should not be 
displayed. 

Specifies that file m e should be used as a source of more 
formats for properties 

Specifies that when selecting a window by hand (that is, if 
neither -name, -root, nor -id isgiven), look at the window 
manager frame (if any) instead of looking for thedient 
window. 

Specifies the name of a property to be removed from the 
indicated window. 

Examine window properties forever, looking for property 
change events. 

Specifies that the format for name should bet or mat and that 
the dformat for name should bedformat. If dformat is missing, 
■= $0+\n" isassumed. 


DESCRIPTION 

For each of these properties its value on the selected window or font is printed using the supplied formatting information, if 
any. If no formatting information issupplied, internal defaults are used. If a property is not defined on theselected window 
or font, not defined is printed as the value for that property. If no property list isgiven, all the properties possessed by the 
selected window or font are printed. 

A window may be selected in one of four ways. First, if the desired window isthe root window, the -root argument may be 
used. If thedesired window is not the root window, it may be selected in two wayson thecommand line, either by id 
number, such asmight be obtained from xwininfo, or by name if the window possesses a name The -id argument selects a 
window by id number in either decimal or hex (must start with ex) while the -name argument selects a window by name. 

The last way to select a window does not involve the command line at all. If noneof -font, -id, -name, and -root are 
specified, a crosshairs cursor is displayed and the user is allowed to choose any visible window by pressing any pointer button 
in thedesired window. If it is desired to display properties of a font as opposed to a window, the -font argument must be 
used. 

Other than the preceding four arguments and the -help argument for obtaining help, and the -grammar argument for listing 
the full grammar for the command line, all the other command-line arguments are used in specifying both the format of the 
properties to be displayed and how to display them. The -ien n argument specifies that at most, n bytes of any given 
property will be read and displayed. This is useful, for example, when displaying the cut buffer on the root window, which 
could run to several pages if displayed in full. 

Normally, each property name is displayed by printing first the property name then its type (if it has one) in parentheses, 
followed by its value. The -notype argument specifies that property types should not be displayed. The -fs argument isused 
to specify a file containing a list of formats for properties, while the -f argument isused to specify the format for one 
property. 
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T heformatting information for a property actually consists of two parts, a format and a dformat. T he format specifies the 
actual formatting of the property (that is, is it made up of words, bytes, or longs?, and so on) while the dformat specifies how 
the property should be displayed. 

The following paragraphs describe how to construct formats and dformats However, for the vast majority of users and uses, 
this should not be necessary as the built-in defaults contain the formats and dformats necessary to display all thestandard 
properties. It should only be necessary to specify formats and dformats if a new property is being dealt with or the user 
dislikes the standard display format. N ew users especially are encouraged to skip this part. 

A format consists of a 0,8, ie, or 32 followed by a sequence of one or more format characters The0,8, is, or 32 specifies 
how many bits per field there are in the property. 

Zero isa special case that means use the field size information associated with the property itself. (Thisisonly needed for 
special cases like type integer, which is actually three different types depending on the size of the fields of the property.) 

A value of 8 means that the property is a sequence of bytes while a value of 16 means that the property is a sequence of 
words The difference between these two liesin thefact that the sequence of words will be byte swapped while the sequence 
of bytes will not be when read by amachine of the opposite byte order of the machine that originally wrote the property. For 
more information on how properties are formatted and stored, consult the Xlib manual. 

After the size of the fields has been specified, it is necessary to specify the type of each field (is it an integer, a string, an atom, 
or what?) This is done using one format character per field. If there are more fields in the property than format characters 
supplied, the last character will be repeated as many times as necessary for the extra fields The format characters and their 
meaning are as follows: 

a Thefield holds an atom number. A field of this type should be 

of size 32. 

b Thefield isa Boolean. A 0 meansfalsewhileanythingelse 

means true 

c Thefield isan unsigned number, a cardinal, 

i Thefield isasigned integer, 

m Thefield is a set of bitflags 1 meaningon. 

s Thisfield and the next ones—until either a 0 or the end of the 

property- represent a sequence of bytes T hisformat character 
is only usable with a field size of 8 and is most often used to 
represent a string. 

x Thefield is a hex number (like c but displayed in hex—most 

useful for displaying window ids and the like). 

An example format is32ica, which isthe format for a property of three fields of 32 bits each—the first holding a signed 
integer, the second an unsigned integer, and the third an atom. 

Theformat of a dformat, unlike that of a format, is not so rigid. T heonly limitationson a dformat isthat one may not start 
with a letter or a dash. This is so that it can be distinguished from a property name or an argument. A dformat is a text string 
containing special characters instructing that various fields be printed at various points in a manner similar to the formatting 
string used by printf. For example the dformat is ( $0, $1 \)\n would render the point 3, -4, which has a format of 32H as 

Any character other than a$, ?, \, or a ( in a dformat prints as itself. To print out a $, ?, \, or (, precede it with a\. For 
example, to print out a $, use \$. Several special backslash sequences are provided as shortcuts. \n will cause a newline to be 
displayed, while \t will cause a tab to bedisplayed. \o, where 0 isan octal number, will display character number 0. 

A $ followed by a number n causes field number n to bedisplayed. The format of the displayed field depends on the 
formatting character used to describe it in the corresponding format. In other words, if a cardinal isdescri bed by c, it will 
print in decimal, while if it is described by an x, it is displayed in hex. 
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If the field is not present in the property (this is possible with some properties), <fieid not avatiabie> isdisplayed instead. 
$n+will display field number n, then a comma, then field number n+i, then another comma, then ... until the last field 
defined. If field n is not defined, nothing isdisplayed. This isuseful fora property that is a list of values 
A ? isused to start a conditional expression, a kind of if-then statement. ?e*p(te«t > will display text if and only if exp 
evaluates to non-zero. This is useful for two things First, it allows fields to be displayed if and only if aflag is set. And 
second, it allows a value such asa state number to be displayed as a name rather than as just a number. The syntax of exp isas 
follows: 

exp ::= term | term=exp | !exp 
term n | $n j mn 

The t operator is a logical not, changing 0 to 1 and any non-zero value to 0. = is an equality operator. Note that internally, all 
expressions are evaluated as 32-bit numbers so -1 is not equal to 65535. = returns 1 if the two values are equal and 0 if not. n 
represents the constant value n while $ n represents the value of field number n. mn is 1 ifflagnumbern in the first field 
having format character m in the corresponding format is 1; 0 otherwise. 

Examples ?m3(count: $3\n) displaysfield 3 with a label of count if and only if flag number 3 (count starts at 0!) is on. 

?$2=0 (True)?! $2=0 (False) displays the inverted value of field 2 asa Boolean. 

In order to display a property, xprop needs both a format and adformat. Before xprop uses its default values of a format of 32x 
and a dformat of 11 = { $0+ }\n", it searches several placesin an attempt to find more specific formats. First, asearch ismade 
using the name of the property. If thisfails, asearch is made using the type of the property. This allows type string to be 
defined with oneset of formats while allowing property wm_name, which isof type string to be defined with a different 
format. In thisway, the display formats for a given type can be overridden for specific properties 
The locations searched arein order: the format, if any, specified with the property namefasin 8x wm_name), theformats 
defined by -f options in last to first order, the contents of the file specified bythe-fs option if any, the contents of the file 
specified by the environmental variablexpROPFORMATS if any, and finally xprop's built-in file of formats. 

Theformat of the files referred to by the -fs argument and the xpropformats variable isoneor more lines of thefollowing 
form: 

Wherename is either the name of a property or the nameof a type format istheformatto be used with name, and dformat is 
thedformatto be used with name. If dformat isnot present,"=$0+\n" isassumed. 

EXAMPLES 

To display the name of the root window: xprop -root wm_name 
To display the window manager hints for the clock: xprop -name xciock wm_hints 
To display the start of the cut buffer: xprop -root -ten 100 cut_buffer 0 
T0 display the point size of thefixed font: xprop -font fixed point_size 
Todisplayall thepropertiesofwindow#0x200007:xprop -id 0x200007 
ENVIRONMENT 

display To get default display. 

xpropformats Specifies the name of a file from which additional formats are 

to be obtained. 

SEE ALSO 

X(l), xwininfo(l) 



M ark Lillibridge (M IT Project Athena) 


X Version 11 Release 6 


xrdb 

xrdb— X server resource database utility 

SYNOPSIS 

xrdb [ -option ... ] [f i I ename ] 


DESCRIPTION 


xrdb is used to get or set the contents of the resource_manager property on the root wi ndow of screen 0, or the 
screen_resources property on the root window of any or all screens, or everything combined. You would normally run this 
program from your X startup file 

M ost X clients use the resource_manager and screen_resources properties to get user preferences about color, fonts, and so on 
for applications. H aving this information in the server (where it is available to all clients) instead of on disk solves the 
problem in previous versions of X that required you to maintain defaults files on every machine that you might use. It also 
allows for dynamic changing of defaults without editing files. 

TheRESOURCE_MANAGER property is used for resources that apply to all screens of the display. The screen_resources property 
on each screen specifies additional (or overriding) resources to be used for that screen. (When there is only one screen, 
screen_resources is normally not used; all resources are just placed in the resource_manager property.) 

Thefile specified by filename (or the contents from standard input if - or no filename is given) is optionally passed through 


theC preprocessor with thefollowingsymbolsdefined, 

SERVERHOST=h o s t n a me 
SRVR_n a me 

HOST=h o s t n a me 
DISPLAY_NUM=num 
CLIENTHOST=hos t name 
CLNT_n a me 

RELEASED um 

REVISIONS urn 

VERSIONS um 

VENDORS vendor" 

VNDR_n a me 

EXT_n a me 


on the capabilities of theserver being used: 

The host name portion of the display to which you are 
connected. 

ThesERVERHOSThostnamestring turned into a legal identifier. 
For example, my-dpy.lcs.mit.edu becomes SRVR my dpy lcs 
mit edu. 

The same as serverhost. 

The number of thedisplay on theserver host. 

T he name of the host on which xrdb is running. 
TheaiENTHOST hostname string turned into alegal identifier. 
Forexample, "expo.lcs.mit.edu" becomesCLNT expo lcs mit 

T he vendor release number for the server. T he interpretation 
of this number will vary depending on vendor. 

T hex protocol minor version supported by this server 
(currently 0). 

T hex protocol major version supported by this server (should 
always be 11). 

A string literal specifying the vendor of theserver. 

The vendor name string turned into a legal identifier. For 
example, "mit x consortium" becomes vndr_mit_x Consortium. 
A symbol is defined for each protocol extension supported by 
theserver. Each extension string name is turned into alegal 
identifier. Forexample, "X3 d-pex" becomes ext_x3d_pex. 
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NUM_SCREENS=nu m 
SCREEN_NUM=niim 
BITS_PER_RGB=n um 


CLASS=v i s u a I cl ass 

CLASS_vi sual cl ass=vi sual i d 
COLOR 

CLASS_visualclass_depth=num 


HEIGHT=num 

WIDTH=nuin 

PLANES=num 

X_RESOLUTION=num 

Y_RESOLUTION=num 

SRVR_name, CLNT_name, VNDR_name, and EXT_name identifiers are 1 
into underscores 


The total number of screens. 

The number of the current screen (from zero). 

The number of significant bitsin an RGB color specification. 
T his is the log base 2 of the number of distinct shades of each 
pri mary that the hardware can generate. N ote that it usually is 
not related to planes. 

One Of StaticGray, Grayscale, StaticColor, Pseudocolor, 
TrueCoior, Directcoior. This is the visual dassof the root 
window. 

The visual dassof the root window in a form you can #ifdef 
on. The value is the numeric id of the visual. 

D efi ned only if CLASS is one Of StaticColor, Pseudocolor, 
TrueCoior, Or DirectColor. 

A symbol isdefined for each visual supported for the screen. 

T he symbol includes the class of the visual and its depth; the 
value isthe numeric id of the visual. (If more than one visual 
has the same class and depth, the numeric id of the first one 
reported by the server is used.) 

The height of the root windowin pixels 
The width of the root window in pixels. 

The number of bit planes (the depth) of the root window. 

T hex resolution of the screen in pixels per meter. 

They resolution of the screen in pixels per meter, 
ormed by changing all characters other than letters and digits 


Lines that begin with an exclamation mark 0) are ignored and maybe used as comments 

Note that sincexrdb can read from standard input, it can be used to change the contents of properties directly from a 

terminal or from a shell script. 


OPTIONS 

xrdb program accepts the following options 

-help This option (or any unsupported option) will cause a brief 

description of the allowable options and parameters to be 
printed. 

-display display Thisoption specifiesthe X server to be used; seex(l). It also 

specifies the screen to use for the -screen option, and it 
specifies the screen from which preprocessor symbols are 
derived forthe -global option. 

-an Thisoption indicates that operation should be performed on 

the screen-independent resource property (resource_manager), 
as well as the screen-specific property (screen_resources) on 
every screen of the display. For example when used in 
conjunction with -query, the contents of all properties are 
output. For -load, -override, and -merge, the input file is 
processed once for each screen. The resources that occur in 
common in the output for every screen are collected, and these 
are applied asthe screen-independent resources The 
remaining resourcesare applied for each individual per-screen 
property. This the default mode of operation. 



-global 


-screen 




■nocpp 

-symbols 


-override 

-merge 


This option indicates that the operation should only be 
performed on the screen-independent resource_manager 
property. 

This option indicates that the operation should only be 
performed on the screen_resources property of the default 
screen of the display. 

This option indicates that the operation should be performed 
on the screen_resources property of each screen of the display. 
For -load, -override, and -merge, the input file is processed for 
each screen. 

This option indicates that changesto the specified properties 
(when used with -load, -override, or -merge) orto the resource 
file (when used with -edit) should be shown on the standard 
output, but should not be performed. 

This option indicates that warning about duplicate entries 
should not be displayed. 

This option specifies the pathname of the C preprocessor 
program to be used. Although xrdb was designed to useCPP, 
any program that acts as a fi Iter and accepts the -d, -i, and -u 
options may be used. 

This option indicates that xrdb should not run the input file 
through a preprocessor before loading it into properties. 

This option indicates that the symbols that are defined for the 
preprocessor should be printed onto the standard output. 

This option indicates that the current contents of the specified 
properties should be printed onto the standard output. N ote 
that since preprocessor commands in the input resource file are 
part of the input file not part of the property, they won't 
appear in the output from thisoption. The-edit option can 
be used to merge the contents of properties back into the input 
resource file without damaging preprocessor commands 
Thisoption indicates that the input should be loaded asthe 
new value of the specified properties replacing whatever was 
there; that is the old contents are removed. Thisisthe default 
action. 

Thisoption indicates that the input should be added to, 
instead of replacing, the current contents of the specified 
properties. N ew entries override previous entries. 

Thisoption indicates that the input should be merged and 
lexicographically sorted with, instead of replacing, the current 
contents of the specified properties 
Thisoption indicates that the specified properties should be 
removed from the server. 

Thisoption indicates that the server should beinstructed not 
to reset if xrdb isthefirst client. This should never be necessary 
under normal conditions, sincexdm and xinit always act asthe 
first client. 

This option indicates that the contents of the specified 
properties should be edited intothegiven file replacing any 
values already listed there. This allows you to put changes that 
you have made to your defaults back into your resource file, 
preserving any comments or preprocessor lines 
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-backup string 
-Dn a me [ =* a I u e ] 


FILES 

Generalizes-/.xdefauits files 

SEE ALSO 

x(l), Xlib Resource M anager documentation, xt resource documentation 

ENVIRONMENT 

display To figure out which display to use. 

BUGS 

T he default for no arguments should be to query, not to overwrite, so that it is consistent with other programs 

AUTHORS 

Bob Scheifler and Phil Karlton, rewritten from the original by J im Gettys 

X Version 11 Release 6 


This option specifies a suffix to be appended to the filename 
used with -edit to generate a backup file. 

This option is passed through to the preprocessor and is used 
to define symbols for use with conditionals such as#ifdef. 
This option is passed through to the preprocessor and is used 
to remove any definitionsof thissymbol. 

This option is passed through to the preprocessor and is used 
to specify a directory to search for files that are referenced with 

#include. 


xrefresh 

xrefresh— Refresh all or part of an X screen 

SYNOPSIS 

xrefresh [-option ...] 

DESCRIPTION 

xrefresh is a simplex program that causes all or part of your screen to be repainted. This is useful when system messages 
have messed up your screen, xrefresh maps a window on top of the desired area of the screen and then immediately unmaps 
it, causing refresh events to be sent to all applications By default, a window with no background is used, causing all 
applicationsto repaint smoothly. However, thevarious options can be used to indicatethat a solid background (of any color) 
or the root window background should be used instead. 

ARGUMENTS 

-black 

-solid col o 


U se a white background. T he screen just appears to flash 
quickly, and then repaint. 

Use a black background (in effect, turning off all of the 
electron gunsto thetube). T hiscan be somewhat disorienting 
as everything goes black for a moment. 

Use a solid background of the specified color. Try green. 

Use the root window background. 



This is the default. All of the windows simply repaint. 

Specifies the portion of the screen to be repainted; see x(l). 
This argument allows you to specify the server and screen to 
refresh; see x(l). 

X DEFAULTS 

Thexrefresh program uses the routine xGetDefauit(3X) to read defaults, so its resource names are all capitalized. 

Black, white, Solid, None, Root D etermineswhat sort of window background to use 

Geometry D eterm in es the area to refresh. Not very useful. 

ENVIRONMENT 

display To get default host and display number. 

SEE ALSO 

x(U 

BUGS 

It should have j ust one default type for the background. 

AUTHORS 

Jim Gettysf Digital Equipment Corporation, M IT Project Athena) 

X Version 11 Release 6 


-geometry WxH+X+Y 
-display display 


Xserver 

xserver— X W indow System display server 

SYNOPSIS 

X [option ... ] 

DESCRIPTION 

x isthe generic namefortheX Window System display server. It isfrequently a link or a copy of theappropriateserver 
binary for driving the most frequently used server on a given machine. 

STARTING THE SERVER 

T hex server is usually started from theX Display M anager program xdm(l). This utility is run from the system boot files and 
takes care of keeping theserver running, prompting for usernames and passwords, and starting up the user sessions. 
Installations that run more than one window system may need to usethexinit(l) utility instead of xdm. However, xinit isto 
be considered a tool for building startup scripts and is not intended for use by end users. Site administrators are strongly 
urged to use xdm, or build other interfaces for novice users. 

T he x server may also be started directly by the user, though this method is usually reserved for testing and is not recom¬ 
mended for normal operation. 0 n some platforms, the user must have special permission to start the x server, often because 
access to certain devices (For example /dev/mouse is restricted.) 

W hen the x server starts up, it typically takes over the display. If you are running on a workstation whose console isthe 
display, you may not be able to log into the console while the server isrunning. 
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OPTIONS 


All of the x servers accept thefollowing command-line options: 


-fc curs or Font 
-fn font 


T hex server runs as the given di s pi ay number , which by default 
iso. If multiplex servers are to run simultaneously on a host, 
each must have a unique display number. See the "Display 
Names" subsection of thex(l) manual page to learn how to 
specify which display number clients should try to use. 

Sdts pointer acceleration (that is, the ratio of how much is 
reported to how much the user actually moved the pointer). 
Disables host-based access control mechanisms Enables access 
by any host, and permits any host to modify the access control 
list. Use with extremecaution.Thisoption exists primarily for 
running test suites remotely. 

Sdts the audit trail level. The default level isl, meaning only 
connection Sections are reported. Level 2 additionally reports 
all successful connectionsand disconnects Level Oturnsoff 
the audit trail. Audit lines are sent as standard error output. 
Specifies a file which contains a collection of authorization 
records used to authenticate access See also the xdm and 
xsecurity manual pages 

D isables certain kinds of error checking, for bug compatibility 
with previous releases (for example to work around bugs in 
R2 and R3 xterms and toolkits). D eprecated. 

Disables backing store support on all screens. 

T urns off key-click. 

Sdts key-dick volume (allowable range 0-100). 

Sdts the visual class for the root window of color screens T he 
class numbers are as specified in the x protocol. N ot obeyed by 
all servers 

Sets name of RG B color database T he default is <xRoot>/iib/ 
xi i /rgb, where <xroot> refers to the root of the X11 install 
tree 

Reads more options from the given file. Options in the file 
may be separated by newlines if desired. If a # character 
appears on a line all characters between it and the next 
newlineare ignored, providing a simple commenting facility. 
The -config option itself may appear in the file. 

C auses the server to generate a core dump on fatal errors 
Sdts the resolution of the screen, in dots per inch. To be used 
when theserver cannot determine the screen size from the 
hardware 

Specifies the types of fonts for which theserver should attempt 
to use deferred glyph loading, whi chf onts can beaii (all fonts), 
none (no fonts), or 16 (16-bit fonts only). 

Sdtsfeep (bell) volume (allowable range: 0-100). 

Sdts default cursor font. 

Sdts the default font. 
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Sdts the search path for fonts This path is a comma-separated 
list of directories that the X server searches for font databases, 
-help pri nts a usage message. 

Causes all remaining command-line arguments to beignored. 
Di sables the xkeyboard extension if present. 

Sets screen saver pattern cycle time in minutes. 

Permits the server to continue running if it fails to establish all 
of its well-known sockets (connection points for clients), but 
establishes at least one 
Turns off auto-repeat. 

Turns on auto-repeat. 

Sdts screen saver time-out time in minutes. 

D isables save under support on all screens 
Sdts pointer acceleration threshold in pixels (that is sets after 
how many pixels pointer acceleration should take effect). 
Causes the server to terminate at server reset, instead of 
continuing to run. 

Sets default connection time-out in seconds 
D isables all testing extensions (for example, xtest, xTrap, 

XTestExtensionl). 

Ignored, for servers started the ancient way (from init). 

Sets video-off screen saver preference. 

Sets video-on screen saver preference 
Forces the default backing-store of all windows to bewhen- 
Mapped. T his isa backdoor way of getting backing-store to 
apply to all windows Although all mapped windows will have 
backing-store, the backing-store attribute value reported by the 
server for a window will bethe last value established by a 
client. If it has never been set by a client, the server will report 
the default value Notusefui. This behavior is required by the 
x protocol, which allows the server to exceed the client's 
backing-store expectations but does not provide a way to tell 
the client that it isdoing so. 

Loads the specified extension at imt. This is a no-op for most 
implementations. 


SERVER DEPENDENT OPTIONS 

Somex servers accept the following options 

-id kilobytes Sets the data space limit of the server to the specified number 

of kilobytes A value of zero makes the data size aslarge as 
possible The default value of-i leavesthedataspacelimit 
unchanged. 

-if files Sdtsthenumber-of-open-fileslimitoftheservertothe 

specified number. A value of zero makes the limit as large as 
possible T he default value of-i leavesthe limit unchanged. 

-is kilobytes Sets the stack space limit of the server to the specified number 

of kilobytes A value of zero makesthestack size as large as 
possible T he default value of-i leaves the stack space limit 
unchanged. 
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-logo T urns on theX Window System logo display in the screen 

saver. There is currently no way to change thisfrom a client. 

noiogo T urns off the X W indow System logo display in the screen 

saver. There is currently no way to change thisfrom a client. 


XDMCPOPTIONS 


x servers that support XD M CP have the following options. (See the X Display M anager Control Protocol specification for 
more information.) 


-query host - name 
-broadcast 


-port port-num 
-class dispi ay-cl ass 


-cookie xdm-auth-bits 


-displaylD display-id 


Enable XD M CP and send Query packets to the specified host. 
EnableXDM CP and broadcastBroadcastQuery packdtstothe 
network. T he first responding display manager will be chosen 
for the session. 

Enable XD M CP and send indirectQuery packets to the 
specified host. 

U se an alternate port number for X D M C P packets M ust be 
specified before any -query, -broadcast, or -indirect options 
XDMCP has an additional display qualifier used in resource 
lookup for display-specific options This option sets that value; 
by default it isMiT-unspecified (not a very useful value). 

W hen testing xdm-authentication-i, a private key is shared 
between theserver and the manager. Thisoption sets the value 
of that private data (not that it is very private, being on the 
command line!). 

Yet another X D M C P-specific value, this one allows the display 
manager to identify each display so that it can locate the 
shared key. 


XKEYBOARD OPTIONS 


x servers that support the xkeyboard extension accept the following options 


-xkbmap fiI ename 


[+-]accessx 
-arl mi 11 i secbt.lS' 


-ar2 mi 11 i seconds 


Base directory for keyboard layout files 

Keyboard description to load on startup 

Enable(+) ordisable(-) AccessX key sequences 

Sets the length oftimein milliseconds that a key must be 

depressed before auto-repeat starts 

Sdts the length oftimein milliseconds that should elapse 

between auto-repeat-generated keystrokes 


M any servers also have device-specific command-line options See the manual pages for the individual servers for more 
details. 


NETWORK CONNECTIONS 

T he x server supports client connections via a platform-dependent subset of the following transport types: TC PIP, U NIX 
Domain sockets, DECnet, and several varieties of SV R4 local connections See the "Display Names" subsection ofthex(l) 
manual page to learn how to specify which transport type clients should try to use 

SECURITY 

Thex server implements a platform-dependent subset of the following authorization protocols: -mit-magiccookie-i, xdm- 
authorization-i, suN-DES-i,and mit-kerberos-5. See the xsecurity(l) manual page for information on the operation of these 
protocols 




Authorization data required by the preceding protocols is passed to the server in a private file named with the-auth 
command-lineoption. Each timetheserver isabout to accept thefirst connection after a reset (or when the server is 
starting), it reads this file. If this file contains any authorization records, the local host is not automatically allowed access to 
the server, and only clients that send one of the authorization records contained in the file in the connection sdtup informa¬ 
tion will be allowed access. Seethexau manual page for a description of the binary format of this file Seexauth(l) for 
maintenance of thisfile and distribution of its contents to remote hosts. 

T hex server also uses a host-based access control list for deciding whether or not to accept connections from clients on a 
particular machine If no other authorization mechanism is being used, this list initially consists of the host on which the 
server is running aswell as any machines listed in thefile/etc/xn. hosts, wheren isthe display number of the server. Each 
li ne of the fi le should contai n either an I nternet hostname (for example expo.ics.mit.edu) or a D ECndt hostname in double 
colon format (for example, hydra::). There should be no leading or trailing spaces on any lines For example, 

joesworkstation 
corporate.company.com 

bigcpu:: 

Users can add or remove hosts from this list and enable or disable access control using the xhost command from the same 
machine as the server. 

T hex protocol intrinsically does not have any notion of window operation permissions or place any restrictions on what a 
client can do; if a program can connect to a display, it has full run of the screen. Sites that have better authentication and 
authorization systems might wish to make use of the hooks in the libraries and the server to provide additional security 
models 

SIGNALS 

T hex server attaches special meaning to thefollowing signals: 

SIGHUP 


SIGTERM 

SIGUSR1 


FONTS 

T hex server can obtain fonts from directories or from font servers. The list of directories and font servers the x server uses 
when trying to open a font is controlled by thefont path. 

The default font path is 

<XRoot>/llb/X11/fonts/misc/, 

<XRoot>/llb/X11/fonts/Speedo/, 

<XRoot>/lib/X11/fonts/Typel/, 

<XRoot>/lib/X11/fonts/75dpi/, 

<XRoot>/lib/X11/fonts/100dpi/ 

where <xRoot> referstotherootoftheXll install tree. 

Thefont path can beset with the-fp option or by xset(l) after the server has started. 


T his signal causes the server to close all existing connections, 
free all resources, and restore all defaults It issent by the 
display manager whenever the main user's main application 
(usually an xterm or window manager) exits to force the server 
to clean up and prepare for the next user. 

This signal causes the server to exit cleanly. 

This signal is used quite differently from either of the above 
W hen the server starts it checks to see if it has inherited 
sigusri assiG_iGN instead of the usual sig_dfl. In thiscase 
the server sends a sigusri to its parent process after it has set 
up the various connection schemes xdm usesthisfeatureto 
recognize when connecting to the server is possible 
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FILES 

/etc/Xn.hosts 

<XRoot>/lib/X11/fonts/misc 
<XRoot>/lib/X11/fonts/75dpi 
<XRoot>/lib/X11/fonts/100dpi 
<XRoot>/lib/X11/fonts/Speedo 
<XRoot>/lib/X11/fonts/Typel 
<XRoot>/lib/X11 /fonts/PEX 
<XRoot>/lib/X11/rgb.txt 
/tmp/.XI1-unix/Xn 
/tmp/rcXn 
/usr/adm/Xnmsgs 

<XRoot>/lib/X11/xdm/xdm-errors 
N ote: <xRoot> refers to the root of the X11 install tree. 


Initial access control list for display number n 


Bitmap font directories 

0 utlinefont directories 
PEX font directories 
Color database 

UNIX domain socket for display number n 
Kerberos5 replay cachefor display number n 
Error log filefor display number n if run from intt(8) 
D efault error log file if the server is run from xdm(l) 


SEE ALSO 

General information: x(l) 

ProtocolsX Window System Protocol,TheX Font Service Protocol, X Display M anager Control Protocol 
Fonts: bdftopcf(l), mkfontdir(l), xfs(l), xisfdnts(l), xfontsei(l), xfd(l), X Logical Font Description Conventions 
Security: Xsecurity(l), xauth(l), xau(l), xdm(l), xhost(l) 

Starting the server: xdm(l), *tnit(l) 

Controlling the server once started: xset(l), xsetroot(l), xhost(l) 

Server-specific man pages: xdec(l), xmacii(l), xsun(l), xnest(l), xvfb(l), xf86 Accei(l), xf86 Mono(l), xf86 svga(1), xf86 

VGA16(1), XFree86(l) 

Server internal documentation: "D efinition of the Porting Layer for the X vll Sample Server," "Strategiesfor Porting the X 
vll Sample Server," "Godzilla's Guide to Porting the X vll Sample Server" 

AUTHORS 

The sample server was originally written by Susan Angebranndt, Raymond Drewry, Philip Karlton, and Todd Newman, 
from Digital Equipment Corporation, with support from a large cast. It hassincebeen extensively rewritten by Keith 
Packard and Bob Scheifler,from M IT. 

X Version 11 Release 6 


xset 

xset— U ser preference utility for X 

SYNOPSIS 

xset [-display display] [-b] [bon/off] [b [volume [pitch [duration]]] [[-] be] 
[-c] [c on/off] [c [volume]] [[-+]fp[-+=] pat h [,path [,...]] ] [fp default] 

[fp rehash] [[ - ]led [integer]] [led on/off] [m[ouse] [accel mult [/accel_div] 
[threshold]]] [m[ouse] default] [p pixel color] [[ -]r [keycode]] [r on/off] 

[s [length [period]]] [s blank/noblank] [s expose/noexpose] [son/off] 

[s default] [s activate] [s reset] [q] 





DESCRIPTION 

This program is used to set various user preference options of the display. 


OPTIONS 

-display display 


fp= path,... 


fp default 
fp rehash 


-fpor fp- 


T his option specifies the server to use; seex(l). 

Theb option controls bell volume, pitch, and duration. This 
option accepts up to three numerical parameters, a preceding 
dash (■), or an on/off flag. If no parameters are given, or the on 
flag is used, the system defaults will be used. If the dash or off 
is given, the bell will be turned off. If only one numerical 
parameter is given, the bell volume will be set to that value, as 
a percentage of its maximum. Likewise, the second numerical 
parameter specifies the bell pitch, in hertz, and thethird 
numerical parameter specifies the duration in milliseconds. 

N otethat not all hardware can vary the bell characteristics 
Thex server will set thecharacteristics of the bell as closely as 
it can to the user's specifications. 

Thebe option controls bug compatibility mode in the server, 
if possible; a preceding dash (■) disables the mode; otherwise 
the mode is enabled. Variouspre-R4 clients pass illegal values 
in some protocol requests and pre-R4 servers did not correctly 
generate errors in these cases. Such clients when run against 
an R4 server, will terminate abnormally or otherwise fail to 
operate correctly. Bug compatibility mode explicitly reintro¬ 
duces certain bugs into thex server, so that many such clients 
can still be run. This mode should be used with care; new 
application development should be done with this mode 
disabled. The server must support the mit-sundry-nonstandard 
protocol extension in order for this option to work. 

Thee option controls key click. This option can takean 
optional value, a preceding dash (■), or an on/off flag. If no 
parameter or theon flag is given, the system defaults will be 
used. If the dash or off flag is used, key click will be disabled. 

If a value from Oto 100 isgiven, it is used to indicate volume; 
as a percentage of the maximum. Thex server will set the 
volume to the nearest value that the hardware can support. 
Thefp= setsthefont path to the entries given in the path 
argument. The entries are interpreted by the server, not by the 
client. T ypically, they are directory names or font server 
names, but the interpretation is server-dependent. 

The default argument causes the font path to be reset to the 
server's default. 

The rehash argument resets the font path to its current value, 
causing the server to reread thefont databases in the current 
font path. This is generally only used when adding new fonts 
to a font directory (after running mkfontdir to re-createthe 
font database). 

The-fp and fp- options remove elements from the current 
font path. They must be followed by a comma-separated list of 
entries. 



Thistp and fp options prepend and append elements to the 
current font path, respectively. They must be followed by a 
comma-separated list of entries 
The led option controls the keyboard leds This controls the 
turning on or off of one or all of the leds It accepts an 
optional integer, a preceding dash (-) or an on/off flag. If no 
parameter or the on flag is given, all leds are turned on. Ifa 
preceding dash or the flag off is given, all leds are turned off. 

If a value between 1 and 32 isgiven, that led will be turned 
on or off depending on the existence of a preceding dash. A 
common led that can be controlled is the caps Lock led. xset 
led 3 would turn led #3 on. xset -led 3 would turn it off. 
The particular led values may refer to different leds on 
different hardware 

Them option controlsthe mouse parameters. T he parameters 
for the mouse are acceleration and threshold. T he accelera¬ 
tion can be specified as an integer, or as a simple fraction. The 
mouse, or whatever pointer the machine is connected to, will 
go acceleration ti mesas fast when ittravelsmorethan 
threshold pixels in ashorttime This way, the mouse can be 
used for precise alignment when it is moved slowly, ydt it can 
be set to travel across the screen in a flick of the wrist when 
desired. One or both parameters for them option can be 
omitted, but if only one is given, it will be interpreted as the 
acceleration. If no parameters or the flag default is used, the 
system defaults will beset. 

The p option controls pixel color values. T he parameters are 
thecolor map entry number in decimal, and a color specifica¬ 
tion. The root background colors may be changed on some 
servers by altering the entries for BiackPixei and whitePixei. 
Although these are often 0 and 1, they need not be Also, a 
server may choose to allocate those colors privately, in which 
case an error will be generated. The map entry must not be a 
read-only color, or an error will result. 

The r option controlsthe auto-repeat. If a preceding dash 
ortheoff flag isused, auto-repeat will be disabled. If no 
parameters or the on flag is used, auto-repeat will be enabled. 

If a specific keycode is specified as a parameter, auto-repeat 
for that keycode is enabled or disabled. 

T he s option lets you set the screen saver parameters This 
option accepts up to two numerical parameters a blank/ 
noblank flag, an expose/noexpose flag, an on/off flag, an 
activate/reset flag, or the default flag. If no parameters or 
the default flag isused, the system will be set to its default 
screen saver characteristics. T he on/off flags simply turn the 
screen saver functionson or off. T he activate flag forces 
activation of screen saver even if the screen saver had been 
turned off. T he reset flag forces deactivation of screen saver 
if it is active. T he blank flag sets the preference to blank the 
video (if the hardware can do so) rather than display a 
background pattern, while nobiank sdtsthe preference to 
display a pattern rather than blank the video. The expose flag 
sets the preference to allow window exposures (the server can 



freely discard window contents), while noexpose sets the 
preference to disable screen saver unless the server can 
regenerate the screens without causing exposure events T he 
length and period parameters for the screen saver function 
determines how long the server must be inactive for screen 
saving to activate and the period to change the background 
pattern to avoid burn in. The arguments are specified in 
seconds If only one numerical parameter isgiven, it will be 
used for the length. 

Theq option gives you information on the current settings. 


These settings will be reset to default values when you logout. 

N otethat not all x implementations are guaranteed to honor all of these options 

SEE ALSO 

X(l), Xserver(l), xmodmap(l), xrdb(l), xsetroot(l) 

AUTHOR 

Bob Scheifler (M IT Laboratory for Computer Science), David Krikorian (M IT Project Athena; Xll version) 

X Version 11 Release 6 
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xsetroot— Root window parameter setting utility for x 

SYNOPSIS 

xsetroot [-help] [-def] [-display d i s p I ay] [-cursor cursorfile maskfile] 

[-cursor_name cursor name] [-bitmap f i I ename ] [-modxy] [-gray] [-grey] 

[-fg color] [-bgcolor] [-rv] [-solid col or ] [-name st r i ng ] 

DESCRIPTION 

Thesetroot program allows you to tailor the appearance of the background (root) window on a workstation display running 
x. Normally, you experiment with xsetroot until you find a personalized look that you like, then put the xsetroot command 
that produces it into your x startup file If no options are specified, or if -def is specified, the window is reset to its default 
state. The -def option can be specified along with other options and only the nonspecified characteristics will be reset to the 
default state. 

Only one of the background color/tiling changing options (-solid, -gray, -grey, -bitmap, and -mod) may be specified at a 
time. 

OPTIONS 

The various options are as follows: 

-help 
-def 


-cursor cursorfiI e maskf i I e 


Print a usage message and exit. 

Reset unspecified attributes to the default values. (Restores the 
background to the familiar gray mesh and the cursor to the 
hollow x shape) 

T his lets you change the poi nter cursor to whatever you want 
when the pointer cursor is outside of any window. C ursor and 
mask files are bitmaps (little pictures), and can be made with 
the bitmap(l) program. You probably want the mask fileto be 
all black until you get used to theway masks work. 
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-gray 


•fg col or 


■name string 


-display di spl ay 

SEE ALSO 

X(l), xset(l), xndb(l) 

AUTHOR 

M ark Lillibridge (M IT Project Athena) 


This lets you change the pointer cursor to one of the standard 
cursors from the cursor font. Refer to Appendix B of the x 
protocol for the names (except that the xc prefix is elided for 
thisoption). 

Use the bitmap specified in thefile to set the window pattern. 
You can make your own bitmap files (little pictures) using the 
bitmap(l) program. The entire background will be madeupof 
repeated "tiles" of the bitmap. 

This is used if you want a plaid-like grid pattern on your 
screen, x and y are integers ranging from 1 to 16. Try the 
different combinations. Zero and negative numbers are taken 
asl. 

M ake the entire background gray. (Easier on the eyes.) 

M ake the entire background grey. 

U secoi or as the foreground color. Foreground and back¬ 
ground colors are meaningful only in combination with 

-cursor, -bitmap, Or -mod. 

Usecoi or asthebackground color. 
Thisexchangestheforeground and background colors 
Normally the foreground color is black and the background 
color iswhite 

This sets the background of the root window to the specified 
color. Thisoption isonly useful on color servers. 

Set the name of the root window to s t r i n g . T here is no default 
value. U sually a name is assigned to a window so that the 
window manager can use a text representation when the 
window is iconified. Thisoption isunused because you can't 
iconify the background. 

Specifies the server to connect to; see x(l). 
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xsm-x Session Manager 

SYNOPSIS 

xsm [-display di spl ay] [-session sessionName] [-verbose] 

DESCRIPTION 

xsm isa session manager. A session isa group of applications, each of which has a particular state xsm allows you to create 
arbitrary sessions For example, you might have a light session, a development session, or an xterminai session. Each session 
can have its own set of applications. W ithin a session, you can perform a checkpoint to save application state, or a shutdown 
to save state and exit the session. When you log back in to the system, you can load a specific session, and you can delete 
sessions you no longer want to keep. 




xsm 


Some session managers simply allow you to manually specify a list of applications to be started in asession. xsm is more 
powerful because it lets you run applications and have them automatically become part of the session. 0 n a simple level, xsm 
is useful because it gives you this ability to easi ly define which applications are in a session. T he true power of xsm, however, 
can betaken advantage of when more and more applications learn to save and restore their state 

OPTIONS 

-display display 

-verbose 

SETUP 

.xsession FILE 

Using xsm requires a change to your .xsession file 

The last program executed by your .xsession file should be xsm. With this configuration, when the user chooses to shut 
down the session using xsm, thesession will truly be over. 

Because the goal of thesession manager is to restart clients when logging into asession, your .xsession file, in general, should 
not directly start up applications Rather, the applicationsshould be started within asession. When xsm shuts down the 
session, xsm will know to restart these applications. Note however, that there are some types of applicationsthat are not 
"session aware", xsm enables you to manually add these applications to your session. (See the subsection titled "Client List.") 

SM_SAVE_DIR ENVIRONMENT VARIABLE 

If the sm_save_dir environment variable is defined, xsm will save all configuration files in this directory. Otherwise, they will 
be stored in the user's home directory. Session-aware applications are also encouraged to save their checkpoint files in the 
sm_save_dir directory, although the user should not depend on thisconvention. 

DEFAULT STARTUP APPLICATIONS 

Thefirst time xsm isstarted, it will need to locate a list of applicationsto start up. For example this list might include a 
window manager, asession management proxy, and an xterm. xsm will first look for the file .xsmstartup in the user's home 
directory. If that file does not exist, it will look for the system.xsm filethat wasset up at installation time Note that xsm 
provides a failsafe option when the user chooses a session to start up. The failsafe option simply loads the default 
applications described above. 

Each line in the startup file should contain a command to start an application. A sample startup file might look this 
<start of file> 
smproxy 
<end of file> 

STARTING A SESSION 

When xsm starts up, it first checks to see if the user previously saved any sessions If no saved sessions exist, xsm starts up a set 
of default applications (as described above in the subsection titled "Default Startup Applications"). If at least one session 
exists, a Session menu is presented. The[ -session sessionName] option forces the specified session to be loaded, bypassing 
thesession menu. 

THESESSION MENU 

TheSession menu presents the user with a list of sessions to choose from. The user can change the currently selected session 
with the mouse, or by using the up and down arrows on the keyboard. N otethat sessions that are locked (that is, running on 
a different display) cannot beloaded or deleted. 


C auses xsm to connect to the specified X display. 

C auses xsm to load the specified session, bypassing the session 
menu. 

T urns on debugging information. 
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Thefollowingoperationscan be performed from the Session menu: 


Load Session 


D el ete Session 


Default/Fail Safe 


C ancel 


Pressing thisbutton will load the currently selected session. 
Alternatively, hitting the Return key will also load the 
currently selected session, or the user can double-click a session 
from the list. 

Thisoperation will delete the currently selected session, along 
with all of the application checkpoint files associated with the 
session. After pressing this button, the user will be asked to 
press the button a second time in order to confirm the 
operation. 

xsm will start up a set of default applications (asdescribed 
earlier in thesection titled "Default Startup Applications"). 

T his is useful when the user wants to start a fresh session, or if 
the session configuration files were corrupted and the user 
wantsafailsafesession. 

Pressing thisbutton will cause xsm to exit. It can also be used 
to cancel a Delete Session operation. 


CONTROLLING A SESSION 

After xsm determines which session to load, it brings up its main window, then starts up all applications that are part of the 

session. The title bar for the session manager's main window will contain the name of the session that was loaded. 

The followi ng options are available from xsm's mai n window: 

Client List Pressing thisbutton brings up a window containing a list of all 

clients that are in thecurrent session. For each client, the host 
machinethatthedient isrunningon is presented. Asdients 
are added and removed from thesession, this list is updated 
to reflect the changes. T he user is able to control how these 
clients are restarted. 

By pressing the V iew Properties button, the user can view the 
session management properties associated with thecurrently 
selected client. 

By pressing the C lone button, the user can start a copy of the 
selected application. 

By pressing the Kill Client button, the user can remove a client 
from thesession. By selecting a restart hint from the Restart 
FI int menu, the user can control the restarting of a client. T he 
following hints are available: 

■ The Restart If Running hint indicates that the client 
should be restarted in the next session if it is connected to 
thesession manager at the end of thecurrent session. 

■ The Restart Anyway hint indicates that the client should 
be restarted in the next session even if it exits before the 
current session is terminated. 

■ The Restart I immediately hint is similar to the Restart 
Anyway hint, but in addition, the client is meant to run 
continuously. If the client exits, thesession manager will 
try to restart it in the current session. 

■ The Restart Never hint indicatesthat the client should not 
be restarted in the next session. 



N otethat all X applications may not be session aware. 
Applicationsthat are not session aware are ones that do not 
support the X Session M anagement Protocol or they cannot 
be detected by the Session M anagement Proxy. (Seethe 
subsection titled "The Proxy."), xsm allows the user to 
manually add such applicationsto the session. Thebottom of 
the Client List window contains a text entry field into which 
application commands can be typed. Each command should 
go on itsown line. This information will be saved with the 
session at checkpoint or shutdown time. W hen thesession is 
restarted, xsm will restart these applications in addition to the 
regular session aware applications. Pressing the Done button 
removes the Client List window. 

TheSession Log window presents useful information about 
thesession. For example, when a session is restarted, all of the 
restart commands will be displayed in the log window. 

By performing a checkpoint, all applicationsthat are in the 
session are asked to save their state N ot every application will 
save its complete state, but at a minimum, thesession manager 
isguaranteed that it will receive the command required to 
restart the application (along with all command-lineoptions). 

A window manager participating in thesession should 
guarantee that the appl ications wi II come back up with the 
same window configurations 

If the session being checkpointed was never assigned a name, 
the user will be required to specify a session name Otherwise, 
the user can perform the checkpoint using the current session 
name or a new session name can be specified. If thesession 
name specified already exists, the user will be given the 
opportunity to specify a different name or to overwrite the 
already existing session. N otethat a session that is locked can 
not be overwritten. 

When performing a checkpoint, the user must specify a save 
Type that informs the applications in thesession how much 
state they should save. 

The Local type indicates that the application should save 
enough information to restore the state as seen by the user. It 
should not affect the state as seen by other users. For example 
an editor would create a temporary file containing the contents 
of its editing buffer, the location of the cursor, and so on. 

The Global typeindicates that the application should commit 
all of its data to permanent, globally accessible storage. For 
example, theeditor would simply save the edited file 
The Both type indicates that the application should do both of 
these. For example the editor would save the edited file, then 
create a temporary file with information such as the location of 
the cursor, and so on. 

In addition to the save Type, the user must specify an interact 
Style. 

The None type indicates that the application should not 
interact with the user while saving state. 
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The Errors type indicates that the application may interact 
with the user only if an error condition arises. 

TheAny type indicates that the application may interact with 
the user for any purpose N otethat xsm will only allow one 
application to interact with the user at a time. 

After the checkpoint is completed, xsm will, if necessary, 
display a window containing the list of applications that did 
not report a successful save of state 

Shutdown A shutdown providesall of theoptionsfound in a checkpoint, 

but, in addition, can cause the session to exit. N otethat if the 
interaction style is Errors or Any, the user may cancel the 
shutdown. T he user may also cancel the shutdown if any of 
the applications report an unsuccessful save of state The user 
may choose to shut down the session with or without 
performing a checkpoint. 

THE PROXY 

Because not all applications have been ported to support the X Session M anagement Protocol, a proxy service exists to enable 
"old" clients to work with the session manager. In order for the proxy to detect an application joining a session, one of the 
following must be true: 

■ Theapplication maps a top-level window containing the wm_client_leader property. Thisproperty providesapointerto 
the client leader window that contains the wm_class, wm_name, wm_command, and wm_client_machine properties. 

or 

■ Theapplication maps a top-level window that does not contain thewM_ci_iENT_LEADER property. H owever, this top-level 
window containsthewM_CLASS, wm_name, wm_command, and wm_clientjiachine properties 

An application that supports the wm_save_yourself protocol will receive a wm_save_yourself client message each time the 
session manager issues a checkpoint or shutdown. This allows the application to save state. If an application does not support 
the wm_save_yourself protocol, then the proxy will provide enough information to the session manager to restart the 
application (using wm_command), but no state will be restored. 

REMOTE APPLICATIONS 

xsm requires a remote execution protocol in order to restart applications on remote machines Currently, xsm supports the 
rstart protocol. In order to restart an application on remote machine X, machineX must haver-start installed. In the 
future additional remote execution protocols may be supported. 

SEE ALSO 

smproxy(l), rstart(l) 

AUTHORS 

Ralph M or (X Consortium), Jordan Brown (Quarterdeck Office Systems) 

X Version 11 Release 6 


xsmclient 

xsmciient— X session manager tester 

SYNOPSIS 


xsmclient [ TBD ] 
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DESCRIPTION 

Thexsmciient program is used to test the session manager 

AUTHOR 

Ralph M or (X Consortium) 

X Version 11 Release 6 


xstdcmap 

xstdcmap-X standard colormap utility 

SYNOPSIS 

xstdcmap [-all] [-best] [-blue] [-default] [-delete map] [-display di spi ay] 

[-gray] [-green] [-help] [-red] [-verbose] 

DESCRIPTION 

The xstdcmap utility can be used to selectively define standard colormap properties. It is intended to be run from auser'sX 
startup script to create standard colormap defi nitions in order to facilitate sharing of scarce colormap resources among 
clients. W here at all possible, colormaps are created with read-only allocations 


OPTIONS 

Thefollowing options may be used with xstdcmap: 
-all 


-blue 

-default 

-delete map 

-display display 

-gray 

-green 


-verbose 


This option indicates that all six standard colormap properties 
should be defined on each screen of the display. Not all screens 
will support visuals under which all six standard colormap 
properties are meaningful, xst-dcmap will determine the best 
allocations and visualsfor the colormap properties of a screen. 
Any previously existing standard colormap properties will be 
replaced. 

This option indicates that the rgb_best_map should be defined. 
This option indicates that the rgb_blue_map should be defined. 
This option indicates that the rgb_default_map should be 
defined. 

This option specifies that a specific standard colormap 
property, or all such properties, should be removed, map may 
be one Of: default, best, red, green, blue, gray, Or all. 
Thisoption specifies the host and display to use; seex(l). 

This option indicates that the rgb_gray_map should be defined. 
Thisoption indicates that the rgb_green_map should be 
defined. 

This option indicates that a brief description of the command¬ 
line arguments should be printed on the standard error. This 
will be done whenever an unhandled argument is given to 
xstdcmap. 

Thisoption indicates that the rgb_red_map should be defined. 
Thisoption indicates that xstdcmap should print logging 
information as it parses its input and defines the standard 
colormap properties 
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ENVIRONMENT 

display To gdt default host and display number 

SEE ALSO 

X(l) 

AUTHOR 

Donna Conversed IT X Consortium) 

X Version 11 Release 6 


xterm 

xterm— Terminal emulator for X 

SYNOPSIS 

xterm [-toolkitoption ...] [-option ...] 

DESCRIPTION 

The xterm program is a terminal emulator for the X Window System. It provides D EC VT102- and Tektronix 4014- 
compatible terminals for programs that can't use the window system directly. If the underlying operating system supports 
terminal resizing capabilities (for example thesiGwiNCH signal in systems derived from 4.3bsd), xterm will use the facilities to 
notify programs running in the window whenever it is resized. 

TheVT102 and Tektronix 4014 terminals all have their own windows so that you can edit text in oneand look at graphics 
in the other at the same time T o maintain the correct aspect ratio (height/width), T ektronix graphics will be restricted to the 
largest box with a 4014's aspect ratio that will fit in the window. This box is located in the upper-left area of the window. 
Although both windows may be displayed at the same time, oneof them is considered the active window for receiving 
keyboard input and terminal output. Thisisthe window that contains the text cursor. The active window can bechosen 
through escape sequences, theVT Options menu in the VT102 window, and the Tek Options menu in the 4014 window. 

EMULATIONS 

TheVT 102 emulation is fairly complete, but does not support smooth scrolling, VT52 mode, the blinking character 
attribute nor the double-wide and double-size character sets termcap( 5 ) entries that work with xterm include xterm, vti02, 
vtleo, and ansi, and xterm automatically searches the termcap file in this order for these entries and then sets the term and the 
termcap environment variables. 

M any of the special xterm features may be modified under program control through a set of escape sequences different from 
thestandard VT 102 escape sequences. (Seethe"Xterm Control Sequences" document.) 

TheT ektronix 4014 emulation is also fai rly good. It supports 12-bit graphics addressing, scaled to the window size. Four 
different font sizes and five different lines types are supported. There is no write-through or defocused mode support. The 
Tektronix text and graphics commands are recorded internally by xterm and may be written to a file by sending the copy 
escape sequence (or through theT ektronix menu, discussed later in this section). The name of thefilewill becoPYyy-MM- 
dd. hh: mm: ss , where yy, MM,dd, hh, mm, and s are the year, month, day, hour, minute, and second when thecoPY was 
performed (the file iscreated in the directory xterm isstarted in, or the home directory for a login xterm). 

OTHER FEATURES 

xterm automatically high lights the text cursor when the pointer enters the window (selected) and unhighlights it when the 
pointer leaves the window (unselected). If the window is thefocus window, then the text cursor is highlighted no matter 
where the pointer is In VT102 mode, there are escape sequences to activate and deactivate an alternate screen buffer, which 
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isthesamesize as the display area of the window. When activated, the current screen issaved and replaced with the alternate 
screen. Saving of lines scrolled off the top of the window is disabled until the normal screen is restored. Thetermcap(5) entry 
for xterm allows the visual editor vi(l) to avitch to the alternate screen for editing and to restore the screen on exit. 

I n either VT102 or T ektronix mode there are escape sequences to change the name of the windows. See xterm C ontrol 
Sequences for details. 

OPTIONS 

The xterm terminal emulator accepts all of the standard X Toolkit command-line options as well as the following (if the 
option begins with a + instead of a-,theoption is restored to its default value): 

-help This causes xterm to print out a verbose message describing its 

options 

-132 N ormally, the VT 102 deccolm escape sequence that switches 

between 80 and 132 column mode is ignored. This option 
causes the deccolm escape sequence to be recognized, and the 
xterm window will resize appropriately. 

This option indicates that xterm should always highlight the 
text cursor. By default, xterm will display a hollow text cursor 
whenever the focus is lost or the pointer leaves the window. 
This option indicates that xterm should do text cursor 
highlighting based on focus 

This option specifies the size of the inner border (the distance 
between the outer edge of the characters and the wi ndow 
border) in pixels The default is 2 . 

Set thevtlOO resource cutToBeglnnlngOfLine to False. 

Sdt the VtlOO resource cutToBeglnnlngOfLine to True. 

Thissets classes indicated by the given ranges to usein 
selecting by words See the subsection "Character Classes." 
This option indicates that newlines should not be cut in line¬ 
mode selections. 

This option indicates that newlines should be cut in line-mode 
selections 

This option specifies the color to use for text cursor. The 
default isto use the same foreground color that is used for text. 
This option indicates that xterm should work around a bug in 
the more(l) program that causes it to incorrectly display lines 
that are exactly the width of the window and are foil owed by a 
line beginning with a tab (the leading tabs are not displayed). 
This option is so named because it was originally thought to 
be a bug in thecurses(3x) cursor motion package 
This option indicates that xterm should not work around the 
more(3x) bug mentioned in the preceding paragraph. 

This option specifies the program (and its command-line 
arguments) to be run in the xterm window. It also sets the 
window title and icon name to bethebasenameofthe 
program being executed if neither -t nor -n are given on 
the command line This must be the last option on the 
command line 

-tb font This option specifies a font to be used when displaying bold 

text. This font must be the same height and width as the 
normal font. I f only one of the normal or bold fonts is 




specified, it will be used as the normal font and the bold font 
will be produced by overstriking thisfont. The default isto do 
overstriking of the normal font. 

Turn on theuseinsertMode resource. 

Turn off theuseinsertMode resource. 

This option indicates that xterm should do jump scrolling. 

N ormally, text is scrolled one line at a time; this option allows 
xterm to move multiple lines at a time so that it doesn't fall as 
far behind. Its use is strongly recommended because it makes 
xterm much faster when scanning through large amounts of 
text. The VT100 escape sequences for enabling and disabling 
smooth scroll as well astheVT Options menu can be used to 
turnthisfeatureon or off. 

This option indicates that xterm should not do jump scrolling. 
This option indicates that the shell that is started in the xterm 
window will be a login shell (that is, the first character of 
argv[ 0 ] will beadash, indicating to the shell that it should 
read the user's .login or .profile). 

This option indicates that the shell that is started should not 
be a login shell (that is, it will be a normal subshell). 

This option indicates that xterm should ringamargin bell 
when the user types near the right end of aline Thisoption 
can be turned on and off from theVT Options menu. 
Thisoption indicates that margin bell should not be rung. 
Thisoption specifies the maximum time between multiclick 
selections 

Thisoption specifies the color to be used for the pointer 
cursor. The default isto use the foreground color. 

This option specifies the number of characters from the right 
end of a line at which themargin bell, if enabled, will ring. 
The default is 10 . 

Thisoption indicates that reverse-wraparound should be 
allowed. This allows the cursor to back up from the leftmost 
column of one line to the rightmost column of the previous 
line This is very useful for editing long shell command lines 
and isencouraged. Thisoption can be turned on and off from 
theVT Optionsmenu. 

Thisoption indicates that reverse-wraparound should not be 
allowed. 

Thisoption indicates that auto-wraparound should be 
allowed. This allows the cursor to automatically wrap to the 
beginning of the next line when it isat the rightmost position 
of a line and text is output. 

Thisoption indicates that auto-wraparound should not be 
allowed. 

Thisoption indicates that xterm may scroll asynchronously, 
meaning that the screen does not have to be kept completely 
up to date while scrolling. This allows xterm to run faster when 
network latencies are very high and istypically useful when 
running across a very large I nterndt or many gateways. 
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This option indicates that xterm should scroll synchronously. 
This option indicates that some number of lines that are 
scrolled off the top of the window should be saved and that a 
scrollbar should be displayed so that thoselines can be viewed. 
Thisoption may be turned on and off from the VT Options 
menu. 

Thisoption indicates that a scrollbar should not be displayed. 
Thisoption indicates that Sun Function Key escape codes 
should be generated for function keys. 

Thisoption indicates that the standard escape codes should be 
generated for function keys 

Thisoption indicates that output to a window should not 
automatically reposition the screen to the bottom of the 
scrolling region. Thisoption can be turned on and off from 
theVT Optionsmenu. 

Thisoption indicates that output to a window should cause it 
to scroll to the bottom. 

Thisoption indicates that pressing a key while using the 
scrollbar to review previous lines of text should cause the 
window to be repositioned automatically in the normal 
position at the bottom of the scroll region. 

Thisoption indicates that pressing a key while using the 
scrollbar should not cause the window to be repositioned. 
Thisoption specifies the number of lines to save that have 
been scrolled off the top of the screen. T he default is 64. 
Thisoption indicates that xterm should start in T ektronix 
mode rather than in VT102 mode Switching between the 
two windows is done using theO ptionsmenus 
Thisoption indicates that xterm should start in VT102 mode. 
This option specifies a series of terminal setting keywords 
followed by the characters that should be bound to those 
functions, similar to the stty program. Allowable keywords 
include intr, quit, erase, kill, eof, eol, swtch, start, stop, 
brk, susp, dsusp, rprnt, flush, weras, and lnext. Control 
characters may be specified as -char (for example, -c or -u) and 
-? may be used to indicate delete. 

Thisoption specifies the name of the terminal type to beset in 
the term environment variable. T his terminal type must exist 
in the termcap(5) database and should have n# and co# entries 
Thisoption indicates that xterm shouldn't write a record into 
the system log file /etc/utmp. 

Thisoption indicates that xterm should write a record into the 
system log file/etc/utmp. 

Thisoption indicates that a visual bell is preferred over an 
audible one Instead of ringing the terminal bell whenevera 
Ctrl+G isreceived, the window will be flashed. 

Thisoption indicates that a visual bell should not be used. 
Thisoption indicates that xterm should wait for the window to 
be mapped the first time before starting thesubprocess so that 
theinitial terminal size settings and environment variables are 
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correct. It is the appl ication's responsibility to catch subse¬ 
quent terminal size changes 

wf This option indicates that xterm show not wait before starting 

the subprocess 

-c This option indicates that this window should receive console 

output. This is not supported on all systems To obtain 
console output, you must be the owner of the console device, 
and you must have read and write permission for it. If you are 
running x under xdm on the console screen, you may need to 
havethesession startup and reset programs explicitly change 
the ownership of the console device in order to get this option 
to work. 

-sc c n This option specifies the last two letters of the name of a 

pseudo-terminal to use in slave mode, plus the number of the 
inherited file descriptor. Theoption is parsed "%c%c%d". This 
allows xterm to beused as an input and output channel for an 
existing program and issomdimesused in specialized 
applications. 


Thefollowing command-line arguments are provided for compatibility with older versions. They may not be supported in 

the next release as the X Toolkit provides standard options that accomplish the same task. 

%geom This option specifies the preferred size and position of the 

Tektronix window. 11 is shorthand for specifying the 
‘tekGeometry resource. 

geom Thisoption specifies the preferred position of theicon 

window. It isshorthand for specifying the *iconGeometry 
resource. 

-t string Thisoption specifies the title for xterm’s windows It is 

equivalent to -title. 

-n string This option specifies the icon name for xterm’s windows. It is 

shorthand for specifying the *iconName resource. N ote that this 
is not the same as the toolkit option -name (see below). The 
default icon nameistheapplication name 

-r Thisoption indicates that reverse video should besimulated by 

swapping the foreground and background colors. It is 
equivalent to -rv. 

-w number Thisoption specifies the width in pixels of the border 

surrounding the window. It is equivalent to -borderwidth or 


Thefollowing standard X Toolkit command-line arguments are commonly used with xterm: 

-bg color Thisoption specifiesthe color to usefor the background of the 

window. The default is white. 

-bd color Thisoption specifiesthe color to use for the border of the 

window. The default is black. 

-bw number Thisoption specifies the width in pixels of the border 

surrounding the window. 

-tg color Thisoption specifiesthe color to usefor displaying text. T he 

default is black. 

-tn font Thisoption specifies the font to beused for displaying normal 

text. The default is fixed. 
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-title st ri ng 


-geometry geometry 

-display display 
-xrm resourcestring 


This option specifies the application name under which 
resources are to be obtained, rather than the default executable 
filename. Name should not contain . or * characters. 

This option specifies the window title string, which maybe 
displayed by window managers if the user so chooses The 
default title is the command line specified after the -e option, 
if any; otherwise the application name. 

This option indicates that reverse video should be simulated by 
swapping the foreground and background colors 
This option specifies the preferred size and position of the 
VT102 window; see x(l). 

This option specifies theX server to contact; see x(l). 

This option specifies a resource string to be used. Thisis 
especially useful for setting resources that do not have separate 
command-lineoptions. 

This option indicates that xterm should ask the window 
manager to start it as an icon rather than as the normal 
window. 


RESOURCES 


The program understands all of the coreX Toolkit resource names and classes as well as the following: 


iconGeometry (class IconGeometry) 


iconName (class IconName) 
termName (class TermName) 

title (class Title) 

ttyModes (class TtyModes) 


uselnsertMode 
(class UselnsertMode) 

utmplnhibit (class Utmplnhibit) 

sunFunctionKeys 
(class SunFunctionKeys) 

waitForMap (class WaitForMap) 


Specifies the preferred size and position of the application 
when iconified. It is not necessarily obeyed by all window 
managers 

Specifies the icon name The default is the application name. 
Specifies the terminal type name to beset in the term 
environment variable. 

Specifies a string that may be used by the window manager 
when displayingthisapplication. 

Specifies a string containing terminal setting keywords and the 
characters to which they may be bound. Allowable keywords 

include Intr, quit, erase, kill, eof, eol, swtch, start, stop, 
brk, susp, dsusp, rprnt, flush, weras, and lnext. Control 
characters may be specified as "char (for example, ~c or "u) and 
*? may be used to indicate delete. This is very useful for 
overriding the default terminal settings without having to do 
an stty every time an xterm is started. 

Force use of insert mode by adding appropriate entries to the 
termcap environment variable This is useful if the system 
termcap is broken. The default isFaise. 

Specifies whether or not xterm should try to record the user's 
terminal in /etc/utmp. 

Specifies whether or not Sun Function Key escape codes 
should be generated for function keys instead of standard 
escape sequences 

Specifies whether or not xterm should wait for the initial 
window map before starting the subprocess The default is 

false. 
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Thefollowing resources are specified as part of thevtlOO widgdt (class VT 100 ): 


allowSendEvents 
(class AllowSendEvents) 


alwaysHighlight 
(class AlwaysHighlight) 


appcursorDefault 
(class AppcursorDefault) 
appkeypadDefault 
(class AppkeypadDefault) 
autoWrap (class AutoWrap) 

bellSuppressTime 
(class BellSuppressTime) 


boldFont (class BoldFont) 

c132 (class C132) 

cutNewline 
(class CutNewline) 

cutToBeginningOfLine 
(class CutToBeginningOfLine) 

charClass (class CharClass) 


Specifies whether or not synthetic key and button 
events (generated using the x protocol sendEvent request) 
should be interpreted or discarded. The default is False, 
meaning they are discarded. N otethat allowing such events 
creates a very large security hole. 

Specifies whether or not xtem should always display 
a highlighted text cursor. By default, a hollow text cursor is 
displayed whenever the pointer moves out of the window or 
the window loses the input focus 
If true, the cursor keys are initially in application mode. 

The default is false. 

If true, the keypad keysare initially in application mode 
The default is false. 

Specifies whether or not auto-wraparound should be enabled. 
The default is true. 

N umber of milliseconds after a bell command is sent during 
which additional bells will be suppressed. D efault is 200. If set 
non-zero, additional bells will also be suppressed until the 
server reports that processing of the first bell has been com¬ 
pleted; this feature is most useful with the visible bell. 
Specifies the name of the bold font to use i nstead of 
overstriking. 

Specifies whether or not the VT102 deccolm escape sequence 
should be honored. The default is false. 

If false, triple-clicking to select a line does not 

include the Newline attheend oftheline. If true, the Newline 

is selected. The default is true. 

If false, triple-clicking to select a line selects only from 
the current word forward. If true, the entire line is selected. 
The default is true. 

Specifies comma-separated lists of character class bindings of 
theform [iow-jhigh:vaiue. These are used in determining 
which sets of characters should be treated the same when 
doing cut and paste. See the section on specifying character 
classes. 


curses (class Curses) 


background 
(class Background) 
foreground 
(class Foreground) 


cursorColor 
(class Foreground) 
eightBitlnput 
(class EightBitlnput) 


Specifies whether or not the last column bug in more(l) should 
be worked around. See the -cu option for details. The default 
is false. 

Specifies the colorto use for the background of the window. 
The default iswhite. 

Specifies the colorto use for displaying text in the window. 
Setting the class name instead of the instance name is an easy 
way to have everything that would normally appear in the text 
color change color. The default is black. 

Specifies the color to use for the text cursor. The 
default is black. 

If true, metacharacters input from the keyboard are presented 
as a single character with the eighth bit turned on. If false, 
metacharacters are converted into a two-character sequence 
with the character itself preceded by ESC. The default istrue. 




eightBitOutput 
(class EightBitOutput) 


font (class Font) 
fontl (class Fontl) 
font2 (class Font2) 
font3 (class Font3) 
font4 (class Font4) 
font5 (class Font5) 
font6 (class Font6) 
geometry (class Geometry) 


hpLowerleftBugCompat 
(class HpLowerleftBugCompat) 


internalBorder 

(class BorderWidth) 

jumpScroll 

(class JumpScroll) 

loginShell 

(class LoginShell) 

marginBeJti 

(class MarginBell) 

multiClickTime 

(class MultiClickTime) 

multiScroll 

(class MultiScroll) 

nMarginBell (class Column) 

pointerColor 

(class Foreground) 

pointerColorBackground 

(class Background) 

pointerShape 

(class Cursor) 

resizeGravity 

(class ResizeGravity) 


reverseVideo 
(class ReverseVideo) 


Specifies whether or not eight-bit characters sent from the 
host should be accepted as is or stripped when printed. The 
default istrue. 

Specifies the name of the normal font. The default is fixed. 
Specifies the name of the first alternative font. 

Specifies the name of the second alternative font. 

Specifies the name of the third alternative font. 

Specifies the name of the fourth alternati ve font. 

Specifies the name of the fifth alternati ve font. 

Specifi es the n ame of the sixth alternati ve font. 

Specifies the preferred size and position of the VT102 
window. 

Specifies whether to work around a bug in H P'sxdb, which 
ignores termcap and always sends ESC F to movetothelower- 
left corner, true causes xterm to interpret ESC F as a request 
to move to the lower-left corner of the screen. T he default is 
false. 

Specifies the number of pixels between the characters and the 
window border. The default is2. 

Specifies whether or not jump scroll should be used .The 
default istrue. 

Specifies whether or not the shell to be run in the window 
should be started asa login shell. The default isfaise. 
Specifies whether or not the bell should be run when the user 
types near the right margin. The default is false. 

Specifies the maximum time in milliseconds between 
multiclick select events. The default is250 milliseconds 
Specifies whether or not scrolling should be done asynchro¬ 
nously. The default is false. 

Specifies the number of characters from the right margin at 
which the margin bell should be rung, when enabled. 

Specifies the foreground color of the pointer. T he default is 

XtDefaultForeground. 

Specifies the background color of the pointer. The default is 

XtDefaultBackground. 

Specifies the name of the shape of the pointer. The default is 

xterm. 

Affects the behavior when the window is resized to be taller or 
shorter. Northwest specifies that the top line of text on the 
screen stay fixed. If the window is made shorter, lines are 
dropped from the bottom; if the window is made taller, blank 
li nes are added at the bottom. T his is compatible with the 
behavior in R4. southwest (the default) specifies that the 
bottom line of text on the screen stay fixed. If the window is 
made taller, additional saved lines will be scrolled down onto 
the screen; if the window is made shorter, lines will be scrolled 
off the top of the screen, and the top saved lines will be 
dropped. 

Specifies whether reverse video should be simulated. The 
default is false. 
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reverseWrap 

(class ReverseWrap) 

saveLines 

(class SaveLines) 

scrollBar 

(class ScrollBar) 

scrollTtyOutput 

(class ScrollCond) 

scrollKey 
(class ScrollCond) 

scrollLines 
(class ScrollLines) 
signallnhibit 
(class Signallnhibit) 

tekGeometry 
(class Geometry) 

(class Teklnhibit) 
tekSmall (class TekSmall) 


tekStartup 
(class TekStartup) 
titelnhibit 
(class Titelnhibit) 


translations 
(class Translations) 

visualBell 
(class VisualBell) 


Specifies whether or not reverse-wraparound should be 
enabled. The default is false. 

Specifies the number of lines to save beyond the top of the 
screen when a scrollbar is turned on. The default is64. 

Specifies whether or not the scrollbar should be displayed. 

The default is false. 

Specifies whether or not output to theterminal should 
automatically cause the scrollbar to go to the bottom of the 
scrolling region. The default istrue. 

Specifies whether or not pressing a key should automatically 
cause the scrollbar to go to the bottom of the scrolling region. 
The default is false. 

Specifies the number of lines that the scroll-back and scroll- 
fo™ actions should use as a default. The default value is i . 
Specifies whether or not the entries in the M ain 0 ptions menu 
for sending signals to xterm should be disallowed. The default 
is false. 

Specifies the preferred size and position of the Tektronix 
window. 

Specifies whether or not the escape sequence to enter 
Tektronix mode should beignored. The default isfaise. 
Specifies whether or not the Tektronix mode window should 
start in its smallest size if no explicit geometry is given. This is 
useful when running xterm on displays with small screens. The 
default is false. 

Specifies whether or not xterm should start up in T ektronix 
mode The default is false. 

Specifies whether or not xterm should remove ti and te 
termcap entries (used to switch between alternate screens on 
startup of many screen-oriented programs) from the termcap 
string. If set, xterm also ignores the escape sequence to switch 
to the alternate screen. 

Specifies the key and button bindingsfor menus, selections, 
"programmed strings," and SO On. See the "ACT 10 N S" 
subsection, later in thissection. 

Specifies whether or not a visible bell (that is, flashing) should 
be used instead of an audible bell when Control-G is received. 
The default is false. 


T hefollowing resources are specified as part of the tek40i4 widget (class Tek4oi4): 


width (class Width) 
height (class Height) 
fontLarge (class Font) 
font2 (class Font) 
font3 (class Font) 
fontSmall (class Font) 
initialFont (class InitialFont) 


Specifies the width of theT ektronix window in pixels. 
Specifies the height of the Tektronix window in pixels 
Specifies the large font to use in the Tektronix window. 
Specifies font number 2 to use in the Tektronix window. 
Specifies font number 3 to use in the Tektronix window. 
Specifies the small font to use in theT ektronix window. 
Specifies which of the four Tektronix fonts to use initially. 

V alues are the same as for the set -tek-text action. T he default 
is large. 
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ginTerminator Specifies what character(s) should follow a GIN 

(class GinTerminator) report or status report. T he possibilities are none, which sends 

no terminating characters, CRoniy, which sends cr, and cr&eot, 
which sends both cr and eot. The default is none 


The resources that may be specified for the various menus are described in the documentation for the Athena simpieMenu 
widget. The name and classes of the entries in each of the menus are listed next. 


ThemainMenu has the following entries: 

securekbd (class SmeBSB) 
allowsends (class SmeBSB) 
redraw (class SmeBSB) 
linel (class SmeLine) 
suspend (class SmeBSB) 

continue (class SmeBSB) 

interrupt (class SmeBSB) 
hangup (class SmeBSB) 
terminate (class SmeBSB) 
kill (class SmeBSB) 
line2 (class SmeLine) 
quit (class SmeBSB) 


Thisentry invokes the secured action. 

Thisentry invokestheallow-send-events(toggle) action. 
Thisentry invokes the redrawo action. 

This is a separator. 

Thisentry invokes the send-signai(tstp) action on systems 
that support job control. 

Thisentry invokes the send-signai(cont) action on systems 
that support job control. 

Thisentry invokes the send-signai(int) action. 

Thisentry invokes the send-signai(hup) action. 

Thisentry invokesthesend-signai(term) action. 

Thisentry invokesthesend-signai(kiii) action. 

This is a separator. 

Thisentry invokes the quit o action. 


ThevtMenu has the following entries: 

scrollbar (class SmeBSB) 
jumpscroll (class SmeBSB) 
reversevideo (class SmeBSB) 
autowrap (class SmeBSB) 
reversewrap (class SmeBSB) 
autolinefeed (class SmeBSB) 
appcursor (class SmeBSB) 
appkeypad (class SmeBSB) 
scrollkey (class SmeBSB) 
scrollttyoutput 
(class SmeBSB) 
allowl32 (class SmeBSB) 
cursesemul (class SmeBSB) 
visualbell (class SmeBSB) 
marginbell (class SmeBSB) 
altscreen (class SmeBSB) 
linel (class SmeLine) 
softreset (class SmeBSB) 
hardreset (class SmeBSB) 
clearsavedlines (class SmeBSB)" 
line2 (class SmeLine) 
tekshow (class SmeBSB) 
tekmode (class SmeBSB) 


Thisentry invokes the set-scroiibar(toggie) action. 
Thisentry invokes the set-jumpscroii(toggie) action. 
Thisentry invokestheset-reverse-video(toggie) action. 
Thisentry invokes the set-autowrap(toggie) action. 

This entry in vokes the set - reversewrap (toggle) action. 
This entry invokes the set -autolinef eed(toggie) action. 
Thisentry invokes the set-appcursor(toggie) action. 
Thisentry invokes the set-appkeypad(toggie) action. 
Thisentry invokestheset-scroii-on-key(toggie) action. 
Thisentry invokes the set-scroll-on-tty-output (toggle) 
action. 

This entry in vokes the set - aiiowi 32 (toggle) action. 
Thisentry invokes the set-cursesemui(toggie) action. 
Thisentry invokestheset-visuaibeii(toggie) action. 
Thisentry invokes the set-marginbell(toggle) action. 
This entry is currently di sabled. 

This is a separator. 

This entry in vokes the soft - reset 0 action. 

This entry in vokes the hard - reset 0 action. 

Thisentry invokes the ciear-saved-iines() action. 

This is a separator. 

Thisentry invokes the set-visibiiity(tek,toggle) action. 
Thisentry invokes the set-terminal-type(tek) action. 
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vthide (class SmeBSB) 

ThefontMenu has the following entries: 

fontdefault (class SmeBSB) 
fontl (class SmeBSB) 
font2 (class SmeBSB) 
font3 (class SmeBSB) 
font4 (class SmeBSB) 
font5 (class SmeBSB) 
font6 (class SmeBSB) 
fontescape (class SmeBSB) 
fontsel (class SmeBSB) 

ThetekMenu has the following entries: 

tektextlarge (class SmeBSB) 
tektext2 (class SmeBSB) 
tektext3 (class SmeBSB) 
tektextsmall (class SmeBSB) 
linel (class SmeLine) 
tekpage (class SmeBSB) 
tekreset (class SmeBSB) 
tekcopy (class SmeBSB) 
line2 (class SmeLine) 
vtshow (class SmeBSB) 
vtmode (class SmeBSB) 
tekhide (class SmeBSB) 


This entry invokes the set -visibility (vt, oft ) action. 

Thisentry invokestheset-vt-font(d) action. 

This entry in vokes the set - vt - font ( i ) action. 

Thisentry invokes the set-vt-font( 2 ) action. 

Thisentry invokes the set-vt-font(3) action. 

Thisentry invokestheset-vt-font(4) action. 

Thisentry invokestheset-vt-font(5) action. 

Thisentry invokestheset-vt-font(6) action. 

Thisentry invokestheset-vt-font(e) action. 

Thisentry invokestheset-vt-font(s) action. 

Thisentry invokes the set-tek-text(i) action. 

Thisentry invokes the set-tek-text( 2 ) action. 

Thisentry invokes the set-tek-text(3) action. 

Thisentry invokes the set-tek-text(s) action. 

This is a separator. 

Thisentry invokesthetek-pageo action. 

This entry in vokes the tek - reset () action. 

Thisentry invokesthetek-copyo action. 

This is a separator. 

This entry invokes the set -visibility (vt, toggle) action. 
Thisentry invokes the set-terminai-type(vt) action. 
Thisentry invokes the set-visibiuty(tek,toggle) action. 


The following resources are useful when specified for the Athena Scrollbar widget: 

thickness (class Thickness) Specifies the width in pixels of the scrollbar. 

background (class Background) Specifies the color to use for the background of the scrollbar. 


foreground (class Foreground) Specifies the color to use for the foreground of the scrollbar. 

The "thumb" of the scrollbar is a simple checkerboard pattern 
alternating pixels for foreground and background color. 


POINTER USAGE 

Once the VT 102 window is created, xterm allows you to select text and copy it within the same or other windows. 
Theselection functions are invoked when the pointer buttons are used with no modifiers, and when they are used with the 
Shift key. The assignment of thefunctions described in this subsection to keys and buttons may be changed through the 
resource database; see the "Actions" subsection later in thissection. 

Pointer button one (usually left) is used to save text into the cut buffer. M ove the cursor to the beginning of thetext, and 
then hold the button down while moving the cursor to the end of the region and releasing the button. The selected text is 
highlighted and issaved in the global cut buffer and made the primary selection when the button is released. Double-clicking 
selects by words. T riple-clicking selects by lines Quadruple-clicking goes back to characters and so on. M ultiple-click is 
determined by the time from button up to button down, so you can change the selection unit in the middle of a selection. If 
the key/button bindings specify that an X selection is to be made xterm will leave the selected text highlighted for as long as 
it isthe selection owner. 










xterm 




Pointer button two (usually middle) "types" (pastes) thetextfrom the primary selection, if any, otherwise from thecut 
buffer, inserting it as keyboard input. 

Pointer button three (usually right) extends the current selection. (Without loss of generality, you can swap "right" and "left” 
everywhere in the rest of this paragraph.) I f pressed while closer to the right edge of the selection than the left, it extends/ 
contracts the right edge of the selection. If you contract the selection past the left edge of the selection, xterm assumes you 
really meant the left edge, restores the original selection, then extends/contracts the left edge of the selection. Extension starts 
in theselection unit mode that the last selection or extension was performed in; you can multiple-dick to cycle through 
them. 

By cutting and pasting pieces of text without trailing new lines, you can take text from several places in different windows 
and form a command to the shell, for example, or take output from a program and insert it into your favorite editor. Since 
thecut buffer is globally shared among different applications, you should regard it as a file whose contents you know. The 
terminal emulator and other text programs should be treating it as if it were a text file; that is, the text is delimited by new 
lines. 

The scroll region displays the position and amount of text currently showing in the window (highlighted) relative to the 
amount of text actually saved. As more text issaved (up to the maximum), the size of the highlighted area decreases. 

Clicking button one with the pointer in the scroll region moves the adjacent line to the top of the display window. 

Clicking button three moves the top line of the display window down to the pointer position. 

Clicking button two moves the display to a position in the saved text that corresponds to the pointer's position in the 
scrollbar. 

U nlike the VT102 window, the T ektronix window does not allow the copying of text. It does allow T ektronix GIN mode, 
and in this mode the cursor will change from an arrow to across. Pressing any key will send that key and the current 
coordinate of the cross cursor. Pressing button one two, or three will return the letters 1, m, and r, respectively. If the Shift 
key is pressed when a pointer button is pressed, the corresponding uppercase letter is sent. To distinguish a pointer button 
from a key, the high bit of the character is set (but this is bit is normally stripped unless the terminal mode is RAW; see 
tty(4) for details). 

MENUS 

xterm hasfour menus: matnMenu, vtMenu, fontMenu, and tekMenu. Each menu pops up under the correct combinations of key 
and button presses M ost menus aredivided into two sections separated by a horizontal line The top portion contains 
various modes that can be altered. A check mark appears next to a mode that is currently active. Selecting one of these modes 
toggles its state. The bottom portion of the menu consists of command entries selecting one of these performs the indicated 
function. 

The xterm menu pops up when the Control key and pointer button one are pressed in a window. ThemainMenu contains 
items that apply to both the VT 102 and Tektronix windows. The Secure Keyboard mode is used when typing in passwords 
or other sensitive data in an unsecured environment. (See the "SECURITY" subsection.) Notable entries in the command 
section of the menu are the Continue, Suspend, Interrupt, Hangup, Terminate and Kill, which send thesiGCONT, sigtstp, 
sigint, sighup, sigterm, and siGKiLL signals, respectively, to the process group of the process running under xterm (usually 
the shell). The Continue function isespecially useful if the user has accidentally typed CTRL-Z, suspending the process. 

The vtMenu sets various modesin theVT102 emulation, and is popped up when theControl key and pointer button two are 
pressed in the VT 102 window. In the command section of this menu, the Soft Reset entry will reset scroll regions This can 
be convenient when some program has left the scroll regionsset incorrectly (often a problem when using VM S or TO PS-20). 
The Full Reset entry will clear the screen, reset tabs to every eight columns and reset the terminal modes (such as wrap and 
smooth scroll) to their initial states just after xterm has finished processing the command-line options. 

The fontMenu setsthefont used in the VT 102 window. In addition to the default font and a number of alternatives that are 
set with resources, the menu offers the font last specified by the Set Font escape sequence (see the document "Xterm Control 
Sequences") and the current selection as a font name (if the primary selection isowned). 
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ThetekMenu sets various modes in the Tektronix emulation, and is popped up when the Control key and pointer button two 
are pressed in the Tektronix window. The current font size is checked in the M odes section of the menu. The page entry in 
theCommand section clearstheTektronix window. 

SECURITY 

X environmentsdiffer in their security consciousness Most servers run under xdm, are capable of using a "magic cookie" 
authorization scheme that can provide a reasonable level of security for many people. If your server is only using a host-based 
mechanism to control access to the server (see xhost(l)), then if you enable access for a host and other users are also 
permitted to run clients on that same host, there is every possibility that someone can run an application that will use the 
basic services of thex protocol to snoop on your activities, potentially capturing a transcript of everything you type at the 
keyboard. This is of particular concern when you want to type in a password or other sensitive data. The best solution to this 
problem isto use a better authorization mechanism that host-based control, but a simple mechanism exists for protecting 
keyboard input in xterm. 

Thexterm menu (see"M enus," earlier in this section) contains a secure Keyboard entry which, when enabled, ensures that all 
keyboard input is directed only to xterm (using the GrabKeyboard protocol request). When an application prompts you for a 
password (or other sensitive data), you can enable secure Keyboard using the menu, type in the data, and then disable secure 
Keyboard using the menu again. Only oneX client at a time can secure the keyboard, so when you attempt to enable secure 
Keyboard, it may fail. In this case, the bell will sound. If the secure Keyboard succeeds, the foreground and background colors 
will be exchanged (as if you selected the Reverse Video entry in the Modes menu); they will be exchanged again when you 
exit secure mode If the colors do not switch, then you should be very suspicious that you are being spoofed. If theapplica- 
tion you are running displays a prompt before asking for the password, it is safest to enter secure mode before the prompt 
gets displayed, and to make sure that the prompt gets displayed correctly (in the new colors), to minimize the probability of 
spoofing. You can also bring up the menu again and makesurethat a check mark appears next to theentry. 

Secure Keyboard mode will be disabled automatically if your xterm window becomes iconified (or otherwise unmapped), or 
if you startup a reparenting window manager (that places a title bar or other decoration around the window) while in Secure 
Keyboard mode. (This is a feature of thex protocol that isn't easily overcome.) When this happens, the foreground and 
background colors will beavitched back and the bell will sound in warning. 

CHARACTER CLASSES 

Clicking the middle mouse button twicein rapid succession will cause all characters of the same class (for example, letters, 
whitespace, punctuation) to be selected. Si nee different people have different preferencesfor what should deselected (for 
example, should filenames be selected as a whole or only the separate subnames?), the default mapping can be overridden 
through the use of the charciass (class charciass) resource 

This resource is a series of comma-separated range: value pairs. The range iseither a single number or low-high in the range 
of Oto 127, corresponding to the ASCI I code for the character or characters to beset. The value is arbitrary, although the 
default table uses the character number of the first character occurring in the set. 

The default table is 


static int charClass[128] = { 
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48, 48, 48, 48, 48, 48, 48, 48, 

48, 48, 58, 59, 60, 61, 62, 63, 

/*@ABC D E F G*/ 

64, 48, 48, 48, 48, 48, 48, 48, 

/* H I J K L M N 0 */ 

48, 48, 48, 48, 48, 48, 48, 48, 

/*P QR S T UVW*/ 

48, 48, 48, 48, 48, 48, 48, 48, 

/*xy z nr */ 

48, 48, 48, 91, 92, 93, 94, 48, 

/*'ab c d e fg */ 

96, 48, 48, 48, 48, 48, 48, 48, 

/*h ijklm no*/ 

48, 48, 48, 48, 48, 48, 48, 48, 

/*p q rs tu v w */ 

48, 48, 48, 48, 48, 48, 48, 48, 

/*x y zf jg" DEL */ 

48, 48, 48, 123, 124, 125, 126, 1}; 

For example, the string 33:48,37:48,45-47:48,64:48 indicates that the exclamation mark, percent sign, dash, period, slash, 
and ampersand characters should be treated the same way as characters and numbers This is useful for cutting and pasting 
electronic mailing addresses and filenames. 


ACTIONS 


It ispossibleto rebind keys (or sequences of keys) to arbitrary stringsfor input by changing thetranslationsfor the vtioo or 
tek4Bi4 widgets. Changing the translations for events other than key and button events is not expected, and will cause 
unpredictable behavior. The following actions are provided for using within the vti 0 @ or tek40i 4 translations resources: 


bell ([percent ]) 
ignore)) 
insert)) 

insert-seven-bitd 

insert-eight-bitd 

insert-selection 
(sourcename [, ...]) 


keymap(name) 


popup-menu(meniiname) 


secured 


Thisaction rings the keyboard bell at the specified percentage 
above or below the base volume. 

Thisaction ignores the event but checks for special pointer 
position escape sequences 

Thisaction inserts the character or string associated with the 
key that was pressed. 

Thisaction is a synonym for insert)). 

Thisaction inserts an eight-bit (M eta) version of the character 
or string associated with the key that was pressed. The exact 
action depends on the value of the eightBitinput resource. 
Thisaction insertsthestring found in theselection or cut 
buffer indicated by sourcename. Sources are checked in 
theorder given (case is significant) until oneisfound. 
Commonly used selections include primary, secondary, and 
clipboard. Cut buffers are typically named cut_buffer 0 
through cut_buffer7. 

Thisaction dynamically defines a new translation table whose 
resource name is name with the suffix Keymap (case issignifi- 
cant). The name None restores the original translation table 
Thisaction displaysthespecified pop-up menu. Valid names 
(case is significant) include mainMenu, vtMenu, fontMenu, and 
tekMenu. 

Thisaction toggles the Secure Keyboard mode described in the 
"Security" subsection, and is invoked from the securekbd entry 
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select-start() 


select-extend() 

(dest name [, ...]) 
select-cursor-start() 

select-cursor-end 

((lestname [, ...]) 

set-vt-font 

(d/l/2/3/4/5/6/e/S 

[, n o r ma I f o n t [, boldfont ]]) 


start-cursor-extend() 
string(st ring) 

scroll-back(count [,units]) 

scroll-forw(count [.units]) 

allow-send-events 
(on/off/toggle) 
redraw)) 

send-signal(si g n a me) 


This action begins text selection at the current pointer 
location. Seethesubsection on "Pointer Usage" for informa¬ 
tion on making selections 

This action tracks the pointer and extends the selection. It 
should only be bound to M otion a/ents 
This action puts the currently selected text into all of the 
selections or cut buffers specified by d e s t n a me. 

Thisaction issimilar to select-start except that it begins the 
selection at the current text cursor position. 

Thisaction issimilar to select-end except that it should 
be used with select-cursor-start. 

Thisaction setsthefont or fonts currently being 
used in the VT102 window. Thefirst argument is a 
single character that specifiesthefont to be used: d orD 
indicate the default font (the font initially used when xterm 
was started), 1 through 6 indicate thefonts specified by the 
fonti through fonts resources, e or e indicate the normal and 
bold fonts that have been set through escape codes (or 
specified asthesecond and third action arguments, respec¬ 
tively), and s ors indicate the font selection (as made by 
programs such asxfontsei(l)) indicated by the second action 
argument. 

Thisaction issimilar to select-start except that the selection 
is extended to the current pointer location. 

Thisaction issimilar to seiect-extend except that the selection 
is extended to the current text cursor position. 

Thisaction inserts the specified text string as if it had been 
typed. Quotation is necessary if the string contains whitespace 
or nonalphanumeric characters If the string argument begins 
with the characters ox, it is interpreted as a hex character 
constant. 

Thisaction scrolls the text window backward so that text that 
had previously scrolled off the top of the screen is now visible 
The count argument indicates the number of units (which 
may be page, half page, pixel, or line) by which to scroll. 
Thisaction scroll issimilar to scroll-back except that it scrolls 
the other direction. 

Thisaction set or toggles the aiiowSendEvents resource and is 
also invoked by the aiiowsends entry in mainMenu. 

Thisaction redraws the window and is also invoked by the 
redraw entry in mainMenu. 

Thisaction sends the signal named by s i g n a me tothexterm 
subprocess (the shell or program specified with the-e 
command-line option) and is also invoked by the suspend, 
continue, interrupt, hangup, terminate, and kill entries in 
mainMenu. Allowable signal names are (case is not significant) 
tstp (if supported by the operating system), suspend (same as 
tstp), cont (if supported by the operating system), int, hup, 
term, quit, alrm, alarm (sameaSalrm), and kill. 

Thisaction sendsasiGHUP to the subprogram and exits It is 
also invoked by the quit entry in mainMenu. 



set-scrollbar(on / of f /1 oggl e) 

set-jumpscroll(on/ off /1 oggl e) 

set-reverse-video(on / of f /1 oggl e) 

set-autowrap(on / of f /1 oggl e) 

set-reversewrap(on/off/toggl e) 

set-autolinefeed(on / off /1 oggl e) 

set-appcursor(on/ off / toggl e) 

set-appkeypad(on/ of f /1 oggl e) 

set-scroll-on-key(on / of f /1 oggl e) 

set-scroll-on-tty-output(on/of f /1 oggl e) 

set-allowl32(on / of f /1 oggl e) 

set-cursesemul(on/ off /1 oggl e) 

set-visual-bell(on / of f /1 oggl e) 

set-marginbell(on/ off /1 oggl e) 

set-altscreen(on/ of f /1 oggl e) 
soft-reset!) 

hard-reset!) 

clear-saved-lines() 

set-terminal-type(type) 

set-visibility(vt/1ek, on / of f /1 oggl e) 

set-tek-text(l arge/ 2/ 3/smal I ) 

tek-page() 


Thisaction toggles the scrollbar resource and isalso invoked 
by the scrollbar entry in vtMenu. 

Thisaction toggles the jumpscroii resource and isalso invoked 
by the jumpscroii entry in vtMenu. 

Thisaction toggles the reversevideo resource and isalso 
invoked by the reversevideo entry in VtMenu. 

Thisaction toggles automatic wrapping of long lines and is 
also invoked by the autowrap entry in vtMenu. 

Thisaction toggles the reversewrap resource and isalso 
invoked by the reversewrap entry in vtMenu. 

Thisaction toggles automatic insertion of line-feeds and isalso 
invoked bytheautolinefeed entry in vtMenu. 

Thisaction toggles the handling Application Cursor Key mode 
and isalso invoked by theappcursor entry in vtMenu. 
Thisaction toggles the handling of Application Key-pad mode 
and isalso invoked by theappkeypad entry in vtMenu. 
Thisaction toggles the scroiiKey resource and isalso 
invoked from the scroiikey entry in vtMenu. 

Thisaction toggles the scrointyOutput resource and isalso 
invoked from thescroiittyoutput entry in vtMenu. 

Thisaction toggles the ci 32 resource and isalso invoked from 
the aiiowi 32 entry in vtMenu. 

Thisaction toggles the curses resource and isalso invoked 
from the cursesemul entry in VtMenu. 

Thisaction toggles the visuaiBeii resource and isalso invoked 
by thevisualbell entry in VtMenu. 

Thisaction toggles the marginBeii resource and isalso invoked 
from the marginbell entry in vtMenu. 

This action toggles between the alternate and current screens. 
Thisaction resets the scrolling region and isalso invoked from 
the softreset entry in VtMenu. 

Thisaction resets the scrolling region, tabs, window size and 
cursor keys, and clears the screen. It isalso invoked from the 
hardreset entry in vtMenu. 

This action does hard - reset () and also clears the history of 
lines saved off the top of the screen. It isalso invoked from the 
clearsavedlines entry in vtMenu. 

Thisaction directs output to either the vt or tek windows, 
according to the type string. It isalso invoked by thetekmode 
entry in vtMenu and the vtmode entry in tekMenu. 

Thisaction controls whether or not the vt or tek windows 
are visible It isalso invoked from thetekshowand vthide 
entries in vtMenu and thevtshowand tekhide entries in tekMenu. 
Thisaction sets font used in theT ektronix window to 
the value Of the resources tektextlarge, tektext2, tektext3, 
and tektextsmaii according to the argument. It isalso 
by the entries of the same names as the resources i n tekMenu. 
Thisaction clearstheTektronix window and isalso invoked 
bythetekpage entry in tekMenu. 
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tek-reset() 

tek-copy() 


visual-bell)) 

TheTektronix window also hasthefollowing action: 

gin-press(l / L / m/ M/ r / R ) 

Thedefault bindings in the VT102 window are 

Shift <KeyPress> Prior: scroll-back(1,halfpage) \n\ 

Shift <KeyPress> Next: scroll-forw(1.halfpage) \n\ 

Shift <KeyPress> Select: select-cursor-start() \ 
select-cursor-end(PRIMARY, CUT_BUFFER0) \n\ 

Shift <KeyPress> Insert: insert-selection(PRIMARY, CUT_BUFFER0) \n\ 

'Meta<KeyPress>: insert-seven-bit() \n\ 

Meta<KeyPress>: insert-eight-bit() \n\ 

ICtrl <Btn1Down>: popup-menu(mainMenu) \n\ 

ILock Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 

!Mod2 Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 

!Mod2 Lock Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 

'Meta <Btn1Down>: select-start() \n\ 

'Meta <Btn1Motion>: select-extend() \n\ 

'Ctrl <Btn2Down>: popup-menu(vtMenu) \n\ 

'Lock Ctrl <Btn2Down>: popup-m 

Thedefault bindings in the Tektronix window are 

'Meta<KeyPress>: insert-seven-bit() \n\ 

Meta<KeyPress>: insert-eight-bit() \n\ 

'Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 

ILock Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 

!Mod2 Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 

!Mod2 Lock Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 

'Ctrl <Btn2Down>: popup-menu(tekMenu) \n\ 

'Lock Ctrl <Btn2Down>: popup-menu(tekMenu) \n\ 

!Mod2 Ctrl <Btn2Down>: popup-menu(tekMenu) \n\ 

!Mod2 Lock Ctrl <Btn2Down>: popup-menu(tekMenu) \n\ 

Shift "Meta<Btn1Down>: gin-press(L) \n\ 

"Meta<Btn1Down>: gin-press(l) \n\ 

Shift 'Meta<Btn2Down>: gin-press(M) \n\ 

'Meta<Btn2Down>: gin-press(m) \n\ 

Shift 'Meta<Btn3Down>: gin-press(R) \n\ 

'Meta<Btn3Down>: gin-press(r) 

Below isasamplehowofthekeymapo action is used to add special keys for entering commonly typed works: 

*VT100.Translations: ((override <Key>F13: keymap(dbx) 

VT100.dbxKeymap.translations: \ 

<Key>F14: keymap(None) \n\ 

<Key>F17: string("next") string(0x0d) \n\ 

<Key>F18: string)"step") string(0x0d) \n\ 

<Key>F19: string)"continue") string)0x0d) \n\ 

<Key>F20: string("print ") insert-selection(PRIMARY, CUT_BUFFER0) 


Thisaction resets theTektronix window and is also invoked 
by the tekreset entry in tekMenu. 

Thisaction copies the escape codes used to generate the 
current window contents to a file in the current directory 
beginning with the namecoPY. It is also invoked from the 
tekcopy entry in tekMenu. 

Thisaction flashes the window quickly. 


Thisaction sends the indicated graphics input code. 











ENVIRONMENT 

xterm sets the environment variables term and termcap properly for the size window you have created. It also uses and sets the 
environment variable display to specify which bit map display terminal to use. The environment variable windowid is set to 
theX window id number of the xterm window. 

SEE ALSO 

resize(l), x(l), pty(4), tty(4) 

Xterm Control Sequences 

BUGS 

Large pastes do not work on some systems. This is not a bug in xterm; it is a bug in the pseudo-terminal driver of those 
systems xterm feeds large pastes to thepty only as fast as the pty will accept data, but some pty drivers do not return enough 
information to know if the write has succeeded. 

M any of the options are not resettable after xterm starts 
0 nly fixed-width, character-cell fonts are supported. 

This program still needs to be rewritten. It should be split into very modular sections with the various emulators being 
completely separate widgets that don't know about each other. Ideally, you'd like to be able to pick and choose emulator 
widgets and stick them into a single control widget. 

T here needs to be a dialog box to allow entry of the Tek copy filename. 

AUTHORS 

Far too many people, including Loretta Guarino Reid (DEC-UEG-WSL), Joel M cCormack (D EC-UEG-WSL), Terry 
Weissman (DEC-UEG-WSL), Edward M oy (Berkeley), Ralph R. Swick(M IT-Athena), M ark Vandevoorde(M IT-Athena), 
Bob M cNamara(DEC-M AD),Jim Gettys(M IT-Athena), BobScheifler (M IT X Consortium), DougM ink(SAO), Steve 
Pitschke(Stellar), Ron Newman (M IT-Athena),Jim Fulton (M IT X Consortium), DaveSerisky (FI P),Jonathan Kamens 
(M IT-Athena) 

X Version 11 Release 6 

Xvfb 

xvfb— Virtual framebuffer X server for X Version 11 

SYNOPSIS 

Xvfb [ option ] ... 

DESCRIPTION 

xvfb is an X server that can run on machines with no display hardware and no physical input devices. It emulates a dumb 
framebuffer using virtual memory. 

The primary use of this server is intended to be server testing. Themfb or cfb code for any depth can be exercised with this 
server without the need for real hardware that supports the desired depths 
A secondary use istesting clients against unusual depths and screen configurations. 
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OPTIONS 

In addition to the normal server options described in thexserver(l) manual page, xvfb accepts thefollowing command-line 
avitches: 


-screen screennum WxHxD 


-pixdepths Iist-of-depths 




Thisoption creates screen screennum and sets its width, height, 
and depth to w, h, and d, respectively. By default, only screen 0 
exists and hasthedimensions 1280x1024x8. 

This option specifies a list of pixmap depths that the server 
should support in addition to the depths implied by the 
supported screens, ust-of-depths is a space-separated list of 
integers that can have values from lto 32. 

Thisoption specifies the directory in which the memory- 
mapped files containing the framebuffer memory should be 
created. (See "Files.") Thisoption only exists on machines that 
have the mmap and msync system calls. 

Thisoption specifies that the framebuffer should be put in 
shared memory. The shared memory ID for each screen will be 
printed by the server. The shared memory is in xwd format. 
Thisoption only exists on machines that support the System V 
shared memory interface. 


If neither -shmem nor -fbdir is specified, the framebuffer memory will be allocated with maiioco. 


FILES 

Thefollowing fileiscreated if the-fbdir option isgiven: 

/Xvfb_screen<n> 

EXAMPLES 

Xvfb :1 -screen 0 1600x1200x32 

Xvfb :1 -screen 1 1600x1200x16 

Xvfb -pixdepths 3 27 
-fbdir /usr/tmp 


xwud -in /usr/tmp/Xvfb screen0 

SEE ALSO 

X(l), Xserver(l), xwd(l), xwud(l), XWDFile.h 


M emory-mapped file containing screen n's framebuffer 
memory, onefile per screen. Thefile is in xwd format. 


The server will listen for connections asserver number 1, and 
screen 0 will be depth 32 1600x1200. 

The server will listen for connections as server number 1, will 
havethedefault screen configuration (onescreen, 
1280x1024x8), and screen 1 will be depth 16 1600x1200. 
The server will listen for connections as server number 0, 
will have the default screen configuration (onescreen, 
1280x1024x8), will also support pixmap depths of 3 and 27, 
and will use memory-mapped files in /usr/tmp for the 
framebuffer. 

D isplays screen 0 of the server started by the preceding 
example. 


AUTHORS 

David P. WigginsfX Consortium, Inc.) 


X Version 11 Release6 
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xvidtune 

xvidtune— Video mode tuner for XFree86 


SYNOPSIS 

xvidtune [ -prev j -next j -unlock j -query j -saver suspendt i me [ of f t i me ]][-toolkitopti on ... ] 

DESCRIPTION 

xvidtune isa client interface to the XFree86 X server video mode extension (XFree86-VidM odeExtension). 

When given one of the nontoolkit options, xvidtune provides a command-line interface to either avitch the video mode or 
get/set monitor powersaver time-outs. 

W ithout any options (or with only toolkit options) it presents the user with various buttons and sliders that can be used to 
interactively adjust existing video modes It will also print the settings in a format suitablefor inclusion in anxF86Config file. 


NOTE 


Theoriginal mode settings can be restored by pressing the r key, andthiscan be used to restore a stable screen in situa¬ 
tions where the screen becomes unreadable. 

Theavailablebuttonsare 

Left 

Right 

Up 


Adjust the video mode so that the display will be moved in the appropriate direction: 

Wider 


Narrower 

Shorter 

Taller 


Adjust the video mode so that the display size is altered appropriately: 


Quit 

Apply 

Auto 


Test 

Restore 

Fetch 

Show 


Exit the program. 

Adjust the current video mode to match theselected settings. 
C ause the Up/D own/Right/Left, Wider/N arrower/Shorter/ 

T aller, Restore and thespecial S3 buttonsto be applied 
immediately. Thisbutton can be toggled. 

Temporarily switch to theselected settings. 

Return thesettingsto their original values. 

Q uery the server for its current settings. 

Print the currently selected settings to stdout in xF86Config 
Modeiine format. The primary selection issimilarly set. 

Switch the xserver to the next video mode. 

Switch the xserver to the previous video mode. 


For some S3-based cards (964 and 968) thefollowing are also available: 

invertvcLK ChangetheVCLK invert/noninvert state. 

Eariysc C hangethe Early SC state. This affects screen wrapping. 
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BiankDeiayi, BiankDeiay2 Set the blank delay values. This affects screen wrapping. 

Acceptable values are in the range 0-7. T he values may be 
incremented or decremented with the +and - buttons, or by 
pressing the+or - keys in the text field. 

For S3-864/868 based cards, invertvcLK and BiankDeiayi may be useful. For S3 Trio32/Trio64 cards, only invertvcLK is 
available. At the moment there are no default setti ngs avai lablefor these chips in the video mode extension and thus this 
feature is disabled in xvidtune. It can be enabled by setting any of the optional S3 commands in the screen section of 
xF86Config, for example using 
blank delay "" 0 

OPTIONS 

xvidtune accepts the standard X Toolkit command-lineoptionsas well as the following: 

Switch the xserver to the previous video mode. 

Switch the xserver to the next video mode. 

Normally, xvidtune will disable theavitching of video modes 
via hot keys while it is running. If for some reason the program 
did not exit cleanly and they are still disabled, the program can 
be rerun with thisoption to reenable the mode switching key 
combinations. 

Set the suspend and off screen saver inactivity time-outs. The 
values are in seconds. 

D isplay the monitor parameters and extended screen saver 
time-outs 

SEE ALSO 

XF86Config(4/5) 

AUTHORS 

Kaleb S. Keithley (X Consortium), additions and modifications by J on Tombs, D avid D awes, and Joe Moss 

X Version 11 Release 6 

xvminitoppm 

xvminitoppm-Convert an XV thumbnail picture to PPM 

SYNOPSIS 

xvminitoppm [xvmi ni pi c ] 

DESCRIPTION 

Reads an XV thumbnail picture (a miniature picture generated by the VisualSchnauzer browser) as input. Produces a 
portable pixmap as output. 

SEE ALSO 

ppm(5), xv( 1) 

AUTHOR 

Copyright (c) 1993 bylngo Wilken 



14 December 1993 
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xwd— Dump an image of an X window 

SYNOPSIS 

xwd [-debug] [-help] [-nobdrs] [-out file] [-xy] [-frame] [-add value] 
[-root j -id i d j -name name ] [-icmap] [-screen] [-display display] 


DESCRIPTION 

xwd isan X Window System window dumping utility, xwd allowsX users to store window imagesin a specially formatted 
dump file This file can then be read by various other X utilities for redisplay, printing, editing, formatting, archiving, image 
processing, and so on. The target window is selected by clicking the pointer in the desired window. The keyboard bell is 
rung once at the beginning of the dump and twice when the dump is completed. 


OPTIONS 

-display display 

-help 

-nobdrs 




-screen 


This argument allows you to specify the server to connect to; 
seex(l). 

Print out the usage: command syntax summary. 

This argument specifies that the window dump should not 
include the pixels that compose the X window border. T his is 
useful in situations in which you may wish to include the 
window contents in a document as an illustration. 

This argument allows the user to explicitly specify the output 
file on the command line The default is to output to standard 
out. 

Thisoption applies to color displaysonly. It selects xy format 
dumping instead of the default z format. 

Thisoption specifies a signed value to be added to every pixel. 
Thisoption indicates that the window manager frame should 
be included when manually selecting a window. 

Thisoption indicates that the root window should deselected 
for the window dump, without requiring the user to select a 
window with the pointer. 

Thisoption indicates that the window with the specified 
resourcei d should be selected for the window dump, without 
requiring the user to select a window with the pointer. 
Thisoption indicates that the window with the specified 
wm_name property should deselected for the window dump, 
without requiring the user to select a window with the pointer. 
N ormally, thecolormap of the chosen window is used to 
obtain RGB values. Thisoption forces the first installed 
colormap of the screen to be used instead. 

Thisoption indicates that the Getimage request used to obtain 
the image should bedoneon the root window, rather than 
directly on the specified window. In this way, you can obtain 
pieces of other windows that overlap thespecified window, 
and more importantly, you can capture menus or other 
popupsthat are independent windows but that appear over the 
specified window. 
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ENVIRONMENT 

display To gdt default host and display number 

FILES 

xwDFiie.h x Window dump file format definition file. 

SEE ALSO 

xwud(l), xpr(l), x( 1) 

AUTHORS 

Tony Della Fera (Digital Equipment Corporation, M IT Project Athena) and William F. Wyatt (Smithsonian Astrophysical 
0 bservatory) 

X Version 11 Release6 


xwdtopnm 

xwdtopnm— Convert an Xll or X10 window dump file into a portable anymap 

SYNOPSIS 

xwdtopnm [xwdfiI e ] 

DESCRIPTION 

Reads an X11 or X10 window dump file as input. Produces a portable anymap as output. T he type of the output file 
depends on the input file. If it's black and white, a pbm file iswritten; if it's grayscale a pgm file else a ppm file. The program 
tells you which type it is writing. 

Using this program, you can convert anything on an X workstation's screen into an anymap. Just display whatever you're 
interested in, do an xwd, run it through xwdtopnm, and then use pnmcut to select the part you want. 

BUGS 

I haven't tested thistool with very many configurations, so there are probably bugs Please let me know if you find any. 

SEE ALSO 

pnmtoxwd(l), pnm(5), xwd(l) 

AUTHOR 

Copyright (c) 1989,1991 byjef Poskanzer. 

11 January 1991 


xwininfo 

xwininfo— Window information utility for X 

SYNOPSIS 

xwininfo [-help] [-id id] [-root] [-name name] [-int] [-children] [-tree] 
[-stats] [-bits] [-events] [-size] [-wm] [-shape] [-frame] [-all] [-english] 
[-metric] [-display display] 
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DESCRIPTION 

xwininfo isa utility for displaying information about windows Various information isdisplayed depending on which options 
areselected. If no options are chosen, -stats isassumed. 

T he user has the option of selecting the target window with the mouse (by clicking any mouse button in the desired 
window) or by specifying its window id on the command line with the -id option. Or instead of specifying the window by 
its id number, the -name option may be used to specify which window isdesired by name There is also a special -root 
option to quickly obtain information on the screen's root window. 


OPTIONS 


-children 


Print out the usage: command syntax summary. 

Thisoption allowstheuserto specify a target window id on 
the command line rather than using the mouse to select the 
target window. This is very useful in debugging X applications 
where the target wi ndow is not mapped to the screen or where 
the use of the mouse might be impossible or interfere with the 
application. 

This option allows the user to specify that the window n a me is 
the target window on the command line rather than using the 
mouse to select the target window. 

Thisoption specifies that X's root window isthe target 
window. This is useful in situations where the root window is 
completely obscured. 

Thisoption specifies that all X window ids should be 
displayed as integer values The default isto display them as 
hexadecimal values. 

Thisoption causes the root, parent, and children windows' ids 
and names of the selected window to be displayed. 

Thisoption is like -children but displays all children 
recursively. 

Thisoption causes the display of various attributes pertaining 
to the location and appearance of the selected window. 
Information displayed includes the location of the window, its 
width and height, its depth, border width, class, colormap id if 
any, map state, backing-store hint, and location of the corners 
Thisoption causes the display of various attributes pertaining 
to the selected window's raw bits and how the selected window 
isto be stored. Displayed information includes the selected 
window's bit gravity, window gravity, backing-store hint, 
backing-planes value, backing pixel, and whether or not the 
window has save-under Set. 

Thisoption causes the selected window's event masks to be 
displayed. Both theeventmask of events wanted by some 
client and the event mask of events not to propagate are 
displayed. 

Thisoption causes the selected window's sizing hints to be 
displayed. Displayed information includes the following: for 
both the normal size hints and thezoom size hints, the user 
supplied location, if any; the program supplied location, if any; 
the user supplied size, if any; the program supplied size, if any; 
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-english 


-all 


-display display 


the minimum size if any; the maximum size, if any; the resize 
increments, if any; and the minimum and maximum aspect 
ratios, if any. 

This option causes the selected window's window manager 
hints to be displayed. Information displayed may include 
whether or not the application accepts input, what the 
window's icon window # and name is, where the window's 
icon should go, and what the window's initial state should be. 
Thisoption causes the selected window'swindow and border 
shape extents to be displayed. 

Thisoption causes window manager frames to be considered 
when manually selecting windows 
Thisoption causes all individual height, width, and xand y 
positionsto bedisplayed in millimeters as well as number of 
pixels based on what the server thinks the resolution is. 
Geometry specifications that are in +x+y form are not changed. 
Thisoption causes all individual height, width, and xand y 
positionsto bedisplayed in inches (and feet, yards, and miles if 
necessary) as well as number of pixels, -metric and -engiish 
may both be enabled at the same time 
Thisoption isaquickwayto ask for all information possible 
Thisoption allows you to specify the server to connect to; see 
x(l). 


EXAMPLE 

Thefollowingisa sample summary taken with no options specified: 

xwininfo: Window id: 0x60000f “xterm" Absolute upper-left X: 2 
Absolute upper-left Y: 85 Relative upper-left X: 0 Relative upper-left Y: 25 
Width: 579 Height: 316 Depth: 8 Visual Class: Pseudocolor Border width: 0 
Class: InputOutput Colormap: 0x27 (installed) Bit Gravity State: 
NorthWestGravity Window Gravity State: NorthWestGravity Backing Store State: 
NotUseful Save Under State: no Map State: IsViewable Override Redirect State: 
no Corners: +2+85 -699+85 -699-623 +2-623 -geometry 80x24+0+58 


ENVIRONMENT 

display To get the default host and display number 


SEE ALSO 

X(l), xprop(l) 

BUGS 

Using -stats -bits shows some redundant information. 

The -geometry string displayed must make assumptions about the window's border width and the behavior of the application 
and the window manager. Asa result, the location given is not always correct. 

AUTHOR 

M ark Lillibridge (M IT Project Athena) 


X Verson 11 Release6 




xwud 

xwud— I mage displayer for X 

SYNOPSIS 

xwud [-in file] [-noclick] [-geometry g e o m] [- display d i s p I ay] 

[-new] [-std <maptype>] [-raw] [-vis <vis-type-or-id>] [-help] [-rv] 
[-plane number ] [ -fg color] [-bgcolor] 



DESCRIPTION 

xwud is an X Window System image undumping utility, xwud allows X users to display in a window an image saved in a 
specially formatted dump file such as produced by xwd(l). 


OPTIONS 

-bg col or 

-display display 
-fg col or 



If abitmap image (or a single plane of an image) isdisplayed, 
thisoption can be used to specify the color to display for the 0 
bits in the image 

Thisoption allows you to specify the server to connect to; see 
x(l). 

If abitmap image (or a single plane of an image) isdisplayed, 
thisoption can be used to specify the color to display for the 1 
bits in the image 

Thisoption allows you to specify the size and position of the 
window. Typically, you will only want to specify the position, 
and let the size default to the actual size of the image 
Print out a short description of the allowable options 
This option enables the user to explicitly specify the input file 
on thecommand line. If no input file is given, the standard 
input is assumed. 

Thisoption forces creation of a new colormap for displaying 
the image. If the image characteristics happen to match those 
of the display, this can get the image on the screen faster, but 
at the cost of using a new colormap (which on most displays 
will cause other windows to go T echnicolor). 

Clicking any button in the window will terminate the 
application, unless this option is specified. Termination can 
always be achieved by typing q, q, or Ctrl 4C. 

You can select a single bit planeoftheimageto display with 
thisoption. Planes are numbered with zero being the least 
significant bit. Thisoption can be used to figure out which 
plane to pass to xpr(l) for printing. 

Thisoption forces the image to be displayed with whatever 
color values happen to currently exist on the screen. This 
option is mostly useful when undumping an image back onto 
the same screen that the image originally camefrom, while the 
original windows are still on the screen, and results in getting 
the i mage on the screen faster. 

If abitmap image (or a single plane of an image) isdisplayed, 
thisoption forces the foreground and background colors to be 
swapped. This may be needed when displaying a bitmap image 
that has the color sense of pixel values 0 and 1 reversed from 
what they are on your display. 
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ENVIRONMENT 

DISPLAY 

FILES 

XWDFile.h 

SEE ALSO 

xwd(l), xpr(l), xstdcmap(l), x(l) 

AUTHOR 

Bob Scheifler (M IT X Consortium) 


Thisoption causes theimageto be displayed usingthe 
specified standard colormap. T he property name is obtained 
by converting the type to uppercase, prepending rgb, and 
appending map. Typical types are best, default, and gray. See 
xstd-cmap(l) for oneway of creating standard colormaps 
Thisoption allows you to specify a particular visual or visual 
class. The default isto pick the"best" one A particular class 
can be specified: StaticGray, Grayscale, StaticColor, 
Pseudocolor, DirectColor, Or TrueColor. 0 r Match Can be 

specified, meani ng use the same class as the source i mage. 
Alternatively, an exact visual id (specific to the server) can be 
specified, either asa hexadecimal number (prefixed with ox) or 
asadecimal number. Finally, default can be specified, 
meaning to use the same class as the colormap of the root 
window. Case is not significant in any of these strings. 


To get default display 


X W indow dump file format definition file 


X Verson 11 Release6 


ybmtopbm 

ybmtopbm- Convert a Bennet Yee "face" file into a portable bitmap 

SYNOPSIS 

ybmtopbm [ f a c e fiI e ] 

DESCRIPTION 

Reads a file acceptable to the face and xbm programs by Bennet Yee (bsy+@cs. cmu.edu). W ritesa portable bitmap as output. 

SEE ALSO 

pbmtoybm(l), pbm(5), face(l), face(5), xbm(l) 

AUTHOR 

Copyright (c) 1991 byJamieZawinski and Jef Poskanzer. 


6 March 1990 
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ytalk 

ytaik— A multiuser chat program. 

SYNOPSIS 

ytalk [-x] username... 


DESCRIPTION 

ytaik (V3.0 Patch Level 1) isin essence a multiuser chat program. It works almost exactly liketheUN IX talk program and 
even communicates with the same talk daemon(s), butYTaik allows for multiple connections 


The username field may be formatted in several different ways: 

name@host 

name#tty 

name#tty@host 

name@host#tty 


Some user on your machine 

Some user on a different machine 

Some user on a particular terminal 

Some user on a particular tty on a different machine 

Same as name#tty@host 


You can specify multiple usernames on the command line for example 

ytalk george fred@hissun.edu marc@grumpy.cc 


The -x option disables the X11 interface (described below). 

For each user on the command line, ytaik will attempt to connect to the talk daemon on thespecified user's host and 
determine if that user has left an invitation for you to call. If not, ytaik leaves an invitation for him and tells histalk daemon 
to send an announcement to his screen. There is not yet a dedicated ytaik daemon, but there will be Right now, ytaik is 
able to communicate with both existing versionsof UNIX talk daemons For any particular host, ytaik will attempt to 
communicate with a talk daemon the caller's host also supports If the two hosts have no daemon in common, then UN IX 
talk will not function at all, but a connection is possible through (and only through) ytaik. 

After a connection has been established between two users they can chat back and forth to their hearts' content. The 
connection isterminated when one of them hitsControl-C or selects Quit from the main menu, 
ytaik is perfectly compatible with UN IX talk and they can even converse with each other without any problems. Flowever, 
manyof the features of ytaik can only operate when you are connected to a user who is also using ytaik. For the rest of this 
document, it will be assumed that all connected users are using ytaik unless otherwise stated. 

If you specified more than one user on the ytaik command line, then ytaik will process and add each user to the conversa¬ 
tion as they respond to your invitation. Aseach new user enters the conversation, the screen isfurther subdivided into 
smaller and smaller windows, one for each connected user. Right now, the number of connected users is limited by the 
number of lines on your terminal (or window), for each connected user needs at least three lines 
ytaik does implement primitive support of the X11 Windowing System. If the environment variable display is set, then 
ytaik attempts to connect to that X server. Further details about the X11 interface (and howto turn it off) are given later in 
thissection. 

As each new user is added to the conversation, ytaik will transmit information about that user to all other connected ytaik 
users so that their screens will also subdivide and incorporate the new user. If the new user is using UN IX talk, then 
information about him will NOT be transmitted, as his screen would be unable to accept multiple connections. I have given 
brief thought to allowing at least the output of UNIX talk users to be transmitted to all connected ytaik users, but I have not 
written any code to do so. Note that even though UNIX talk cannot handle multiple connections, itisstill possible for ytaik 
to handle multiple UNIX "talk" connections For example, george (using ytaik) could communicate with fred and joe (both 
using U NIX talk), but fred and joe would be unaware of each other. The best way to understand the limitationsthat UNIX 
"talk" places on ytaik isto test various connections between the two and see how things work. 



Parti: User Commands 


728 


ESCAPE MENU 

Whenever you are using ytaik, you can hit the Escape key to bring up a menu that at this moment has these options: 
a Add a user 

d D elete a user 

o Options 

S Shell 

u User list 

w Output user to file 

q Quit 

By choosing option a, you are given the opportunity to type the name of any user you wish to include into the conversation. 
Again, ytalk will accept an invitation from that user if an invitation exists, or will leave an invitation and ring the given user. 
By choosing option d, you can select the name of a connection to terminate. 

By choosing option o, you can view and/or modify any of the ytaik options (See the "0 ptions" subsection for a list of ytaik 
options) 

By choosing option s, you can invoke a shell in your ytaik window. All other users will see what happens in your shell, ytaik 
will automatically resize your window down to the size of the smallest window you are connected to, in order to ensure that 
all users always see thesame thing. 

The u option displays a list of connected and unconnected users as well as their window sizes and what version of talk 
software they are running. 

By choosing option w, you can select any connected user and type the name of a file, and all further output from that user 
will be dumped to the specified file. Thefile, if it exists, will be overwritten. If you choose w and the same user again, further 
output to the file will be terminated. 

Oh, one other thing: when user A attempts to ytaik to user B, but user B is already ytalking with user C, user A's ytaik 
program will realize that user B isalready using ytaik, and will communicate with user B's ytaik program directly in order to 
initialize the conversation. User B will see a nice windowed message such as 
Do you wish to talk with user A? 

and he will be prompted for a yes/no answer. This, in my opinion, is much preferable to blitting the announcement message 
and messing up user B's screen. 

RUNTIMEOPTIONS 

When you select Options from the main menu, you are given the opportunity to edit the ytaik options. The current options 
are 


s Turn scrolling [off/on] 

w Turn word-wrap [off/on] 

i Turn auto-import [off/on] 

v Turn auto-invite [off/on] 

r Turn auto-rering [off/on] 

a Turn asides [off/on] 

If scrolling isturned on, then a user's window will scroll when he reaches the bottom, instead of wrapping back around to 
the top. 

If word-wrap isturned on, then any word that would overextend the right margin will be automatically moved to the next line 
on your screen. 
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If auto-import isturned on, then ytaik will assume that you wish to talk to any users that connect to other ytaik users that 
are connected to you. T hat last sentence does make sense; try again, ytaik will add these users to your session automatically, 
without asking you for verification. 

If auto-invite isturned on, then ytaik will automatically accept any connection requested by another user and add the user 
to your session. You will not be asked for verification. 

If auto-rering isturned on, then ytaik will automatically re-ring any user who does not respond to your invitation within 30 
seconds You will not be asked for verification. 

If asides isturned on (it may not be available), then keyboard input received while the input focus isin a specific user's 
window will only be sent to that user. (Seethe"Xll Interface^’ subsection.) 

Any of these options can be set to your preference in your .ytaikrc file, as described in the next subsection. 

YTALK STARTUP FILE 

If your home directory contains a file named .ytaikrc, then ytaik will read this file while starting up. All ytaik runtime 
options as well assome startup options, can beset in thisfile. 

SETTING BOOLEAN OPTIONS 

Boolean optionscan be preset with thefollowing syntax: 

turn option [off j on] 

where opt i on is one of scrolling, word-wrap, auto-import, auto-invite, auto-rering, asides, Orx. Setting these Options Works 
just like described earlier in this section. T urningx on or off will enable or disable the X11 Interface For example, one could 
enable word-wrap with theline: 
turn word-wrap on 

SETTING READDRESS MODES 

The purpose of readdressing isto allow ytaik connections across point-to-point network gateways where the local machines 
know themselves by a different address (and typically hostname) than the remote machines. The basic syntax of a readdress 
command is this: 

readdress from-address to- address domain 

The readdress statement simply makes a claim that the machinefs) in domai n communicate with themachine(s) atfrcfe 
address bysendinga packet to to - address . Because most users have no use for this whatsoever, I 'I I descri be it only briefly. 

T H IS IS NOT ROUTING. For example my machine at home is connected via PPP to the network at my office M y 
machine at home thinks its Ethernet address is 192. iss. 253.1 and its hostname is "talisman, com". The network at my office 
has the address i92.67.i4i .0. When I'm connected via PPP, my home machine is placed into the office network as address 
192 . 67 . 141 . 9 with hostname "talisman.austin.eds.com". 

ytaik needs to know that if it is running on domain 192.67.141.0 and receives packets from 192.188.253.1 that it should 
respond to 192.67.141.9, not 192.188.253.1. Right? Right. Okay, okay, okay. I put this line into my .ytaikrc on both ends: 

readdress talisman talisman.austin.eds.com 192.67.141.0 

On my home end, this translates to 

readdress 192.188.253.1 192.67.141.9 192.67.141.0 

which tells my home machine to advertise itself as 192 . 67 . 141 . 9 instead of 192.188.253.1 when ytalking to machi nes on the 
network 192.67.141.0.0 n the office end, the readdress command translates to 

readdress 192.67.141.9 192.67.141.9 192.67.141.0 


which the office machines basically ignore 

Enough. For more information on howto use this, consult the source code or send me a letter.:-) 
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Xll INTERFACE 

If the display environment variable is defined when ytaik starts up, then ytaik will attempt to communicate with thatX 
server. A window will be created for you and each user you are connected to. TheXll Interface can be disabled either by 
specifying -x on the command line or by putting this line into your. ytaikrc file: 

turn X off 

A window iscreated for each individual user in the conversation. If theinput focusisin the main window (theonewith 

ytaik in the title bar) then anything typed will be sent to all connected users If the input focus is in one of the user's 

windows, then anything typed will be sent as an aside to only that user. If the aside option isturned off, then ytaik will beep 

and not accept anything typed when the input focus is not in the mai n window. 

ytaik consults the Xll ResourceD atabase for these user-definable configuration options 

ytaik. display: X server to connect to, defaulting to the display environment variable. 

ytaik. reverse: Reverse black/white pixels. 

ytaik. font: Font to use, defaulting to 9xis. 

ytaik.geometry: Window Size defaulting to 80x24. 

FUTURE WORK 

Work is being done on the following ideas: 

■ Private conversations that do not get interrupted or transmitted to all ytaik connections 

■ A dedicated ytaik daemon 


FILES 

Systemwide defaults file 

User's local configuration file Thisfile overrides options set in 
the system ytaikrc file 


/usr/local/etc/ytalkrc 
$H0ME/.ytaikrc 


AUTHOR 

Britt Yenne (yenne@austin.eds.com) 

CONTRIBUTORS 

Special thanks to Carl Edman for numerous code patches, beta testing, and comments I think thisguy spends as much time 
on ytaik as I do. Special thanks to Tobias H ahn and Geoff W. for beta testing and suggestions Thanks to Sitaram 
Ramaswamyfortheoriginal ytaik man page Thanks to M agnusHammerin for Solaris 2* support. Thanks to Jonas 
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yuvplittoppm 

yuvpiittoppm- Convert a y-, au-, and av- file into a portable pixmap. 

SYNOPSIS 

yuvsplittoppm b a s e n a me width height [-ccir601] 



zcmp, zdiff 




DESCRIPTION 

Reads three files, containing the YU V components, asinput. These files are basename.Y, basename.u and basename.v. Produces 
a portable pixmap on stdout. 

Since theYUV files are raw files, the dimensionswidth and height must be specified on the command line 

OPTIONS 

-ccir60i AssumesthattheYUV triplets are scaled into the smaller range 

of theCCIR 601 (M PEG) standard. Otherwise thejFIF 
(JPEG) standard is assumed. 

SEE ALSO 

ppmtoyuvsplit(l), yuvtoppm(l), ppm(5) 

AUTHOR 

M arcel Wijkstra (<wijkstra@fwi.uva.nl>), based on ppmtoyuvsplit 

26 August 1993 


yuvtoppm 

yuvtoppm— C onvert Abekas YU V bytes into a portable pixmap 

SYNOPSIS 

yuvtoppm width height [ i ma g e d a t a ] 

DESCRIPTION 

Reads raw Abekas YU V bytes asinput. Produces a portable pixmap as output. Theinput file isjust YU V bytes You have to 
specify the width and height on the command line si nee the program obviously can't get them from the file Themaxvai is 
assumed to be 255. 

SEE ALSO 

ppmtoyuv(l), ppm(5) 

AUTHOR 

M arc Boucher (<marc@Postimage.C0M>)), based on ExampleConversion Program, A60/A64 Digital Video InterfaceM anual, 
page 69. Copyright (c) 1991 by D H D Postlmage, Inc. Copyright (c) 1987 by Abekas Video Systems Inc. 

25 March 1991 


zcmp, zdiff 

zcmp, zdiff— Compare compressed files 

SYNOPSIS 

zcmp [ cmp_options ] filel [ file2 ] 
zdiff [diff_options ] filel [ file2 ] 
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DESCRIPTION 

zcmp and zdiff are used to invoke the cmp orthediff program on compressed files All optionsspecified are passed directly to 
cmp or diff. If only onefile isspecified, then thefiles compared are fiiei and an uncompressed fiiei.gz. If two files are 
specified, then they are uncompressed if necessary and fed to cmp or diff. T he exit status from cmp or diff is preserved. 

SEE ALSO 

cmp(l), diff(l), zmore(l), zgrep(l), znew(l), zforce(l), gzip(l), gzexe(l) 

BUGS 

M essagesfrom the cmp or diff programs refer to temporary filenames instead of those specified. 

zeisstopnm 

zeisstopnm- Convert a Zeissconfocal file into a portable anymap 

SYNOPSIS 

zeisstopnm [- p g m j -ppm][zei ssfi I e ] 

DESCRIPTION 

Reads a Zeiss confocal file as input. Produces a portable anymap as output. The type of the output file depends on theinput 
file—if it's grayscale a pgm file will be produced; otherwise it will be a ppm file The program tells you which type it is 
writing. 

OPTIONS 

-pgm Force the output to be a pgm file 

-ppm Force the output to be a ppm file 

SEE ALSO 

pnm(5) 

AUTHOR 

Copyright (c) 1993 by 0liver Trepte. 

15Junel993 


zfonce 

ztorce— Force a .gz extension on all gzip files 

SYNOPSIS 

zforce [ name ... ] 

DESCRIPTION 

ztorce forcesa .gz extension on all gzip files so that gzip will not compressthem twice. Thiscan be useful for files with 
names truncated after a file transfer. On systems with a 14-character limitation on filenames, theoriginal nameistruncated 
to make room for the .gz suffix. For example, 12345678901234 is renamed to 12345678901 .gz. A filename such asfoo.tgz is left 
intact. 



zmore 
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SEE ALSO 

gzip(l), znew(l), zmore(l), zgrep(l), zdiff(l), gzexe(l) 


zgrep 

zgrep — Search possibly compressed files for a regular expression 

SYNOPSIS 

zgrep [ grep_options ] [-e] pattern filename... 

DESCRIPTION 

zgrep isused to invokethe grep on compressed orgziped files. All options specified are passed directly to grep. If no file is 
specified, then the standard input is decompressed if necessary and fed to grep. Otherwise, the given files are uncompressed if 
necessary and fed to grep. 

If zgrep is invoked aszegrep or ztgrep, then egrep ortgrep isused instead of grep. If theGREP environment variable isset, 
zgrep uses it as the grep program to be invoked. For example 

for sh: GREP=fgrep zgrep string files for csh: (setenv GREP fgrep; zgrep string files) 

AUTHOR 

C harles Levert ( Charleston™. polymtl. ca) 

SEE ALSO 

grep(l), egrep(l), fgrep(l), zdiff(l), zmore(l), znew(l), zforce(l), gzip(l), gzexe(l) 


zmore 

zmore— File perusal filter for crt viewing of compressed text 

SYNOPSIS 

DESCRIPTION 

zmore isafilter that allows examination of compressed or plain text files one screenful at a time on a soft-copy terminal, zmore 
works on files compressed with compress, pack, orgzip, and also on uncompressed files. If a file does not exist, zmore looks for 
a file of the same name with the addition of a .gz, .z, or .z suffix. 

zmore normally pauses after each screenful, printing -More- at the bottom of the screen. If the user then types a carriage 
return, one more line isdisplayed. If the user hits a space, another screenful isdisplayed. Other possibilities are enumerated 
later. 

zmore looks in thefile /etc/termcap to determine terminal characteristics, and to determinethe default window size. On a 
terminal capableof displaying 24 lines, thedefault window size is 22 lines To use a pager other than the default more, set 
environment variable pager to the name of the desired program, such as less. 

Other sequences that may be typed when zmore pauses, and their effects are as follows (i is an optional integer argument, 
defaulting to i): 

<space> D isplay i more lines (or another screenful if no argument is 

given). 

'd Display 11 more lines (a "scroll"). If i is given, then the scroll 

size is set to i. 

d Sameas'D(controi-D) 
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Same as typing a space except that i, if present, becomes the 
new window size N ote that the window size reverts back to 
the default at the end of the current file. 

Skip i lines and print a screenful of lines. 

Skip i screenfuls and print a screenful of lines 
Q uit reading the current file; go on to the next (if any). 

When the prompt -More-(Next file: file) is printed, this 
command causes zmore to exit. 

When the prompt -More-(Next file: fi i e) is printed, this 
command causes zmore to skip the next file and continue 
Display the current line number. 

Search for the i th occurrence of the regular expression expr. If 
the pattern is not found, zmore goes on to the next file (if any). 
Otherwise, a screenful isdisplayed, starting two lines before 
the place where the expression was found. The user's erase and 
kill characters may be used to edit the regular expression. 
Erasing back past the first column cancels the search 
command. 

Search for the i th occurrence of the last regular expression 
entered. 

Invokea shell with command. The character 1 in command is 
replaced with the previous shell command. The sequence u is 
replaced by i. 

Q uit reading the current file; go on to the next (if any) (same 
asq or q). 

(dot) Repeat the previous command. 

The commands take effect immediately; that is, it is not necessary to type a carriage return. U p to the time when the 
command character itself is given, the user may hit the line kill character to cancel the numerical argument being formed. I n 
addition, the user may hit the erase character to redisplay the -More- message. 

At any time when output is being sent to the terminal, the user can hit the quit key (normally Control- n). zmore will stop 
sending output, and will display the usual -More- prompt. T he user may then enter one of the preceding commandsin the 
normal manner. U nfortunately, some output is lost when this is done because any characters waiting in the terminal's output 
queue are flushed when the quit signal occurs 

The terminal is set to noecho mode by this program so that the output can be continuous What you type will thus not show 
on your terminal, except for the / and i commands 

If the standard output is not a teletype, then zmore acts just like zcat, except that a header is printed before each file 

FILES 

/etc/termcap Terminal database 

SEE ALSO 

more(l), gzip(l), zdiff(l), zgrep(l), znew(l), zforce(l), gzexe(l) 

znew 

znew— RecompressZ files to GZ files 

SYNOPSIS 



Ft v9PK] 



znew 
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DESCRIPTION 

znew recompresses fils from Z (compress) format to GZ (gzip) format. If you want to recompress a file already in gzip 
format, rename the file to forcea .z extension, then apply znew. 

OPTIONS 


SEE ALSO 

gzip(l), zmore(l), zdiff(l), zgrep(l), zforce(l), gzexe(l), compress(l) 

BUGS 

znew does not maintain the timestamp with the -p option if cpmod(l) is not available and touch(l) does not support the -r 
option. 


Force recompression from Z to GZ format even if a GZ file 
already exists 

Test the new files before deleting originals. 

Verbose. Display the name and percentage reduction for each 
filecompressed. 

Use the slowest compression method (optimal compression). 
Use pipes for the conversion to reduce disk space usage. 

Keep a Z file when it issmaller than theGZ file. 





System Calls 
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intro 

intro— I ntroduction to system calls 

DESCRIPTION 

This chapter describes the Linux system calls. 

CALLING DIRECTLY 

In most cases, it is unnecessary to invoke a system call directly, but there are times when thestandard C library does not 
implement a nice function call for you. 

SYNOPSIS 

#include <linux/unistd.h> 

A _syscaii macro 
Desired system call 

SETUP 

The important thing to know about a system call is its prototype. You need to know how many arguments, their types, and 
thefunction return type Six macros make the actual call into the system easier. They havetheform 

syscallX(t ype .name ,t ypel ,ar gl ,t ype2 ,ar g2....) 

where 

x 0-5, which are the number of arguments taken by the system call 

type T he return type of the system call 

n a me The name of the system call 

typeN The Nth argument's type 

a r g n The name of the Nth argument 

These macros create a function called name with theargumentsyou specify. 0 nee you includesyscall () in your source file, 
you call the system call by n a me. 

EXAMPLE 

struct sysinfo s_info; 
int error; 


error = sysinfo(&s_info); 

printf("code error = %d\n", error); 

printf("Uptime = %ds\nLoad: 1 min %d / 5 min %d / 15 min %d\n" 
"RAM: total %d / free %d / shared %d\n" 

■Memory in buffers = %d\nSwap: total %d / free %d\n" 
■Number of processes = %d\n", 
s_info.uptime, s_info.loads[0], 
s_info.loads[1], s_info.loads[2], 
s_info.totalram, s_info.freeram, 
s_info.sharedram, s_info.bufferram, 
s_info.totalswap, s_info.freeswap, 
s_info.procs); 
return(0); 





exit 
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SAMPLE OUTPUT 

code error = 0 
uptime = 502034s 

Load: 1 min 13376 / 5 min 5504 / 15 min 1152 

RAM: total 15343616 / free 827392 / shared 8237056 

Memory in buffers = 5066752 

Swap: total 27881472 / free 24698880 

Number of processes = 40 

NOTES 

T he _syscaii() macros do not produce a prototype. You might have to create one, especially for C ++ users. 

System calls are not required to return only positive or negative error codes. You need to read the source to be sure how it 
will return errors Usually, it is the negative of a standard error code, for example, -eperm. The_syscaii() macroswill return 
the result r of the system call when r is nonnegative but will return -i and set the variable errno to -r when r is negative. 
Some system calls, such asmmap, require more than five arguments These are handled by pushing the arguments on the stack 
and passing a pointer to the block of arguments. 

W hen defining a system call, theargument types must be passed by value or by pointer (for aggregates such asstructs). 

FILES 


/usr/include/linux/unistd.h 

AUTHORS 

Look at the header of the manual page for the author(s) and copyright conditions N ote that these can be different from page 
to page. 

Linux 1.2.13, 22 May 1996 


exit 

exit— Terminate the current process 

SYNOPSIS 

#include <unistd.h> 

DESCRIPTION 

exit terminates the calling process immediately. Any open file descriptors belonging to the process are closed; any children of 
the process are inherited by process i, init, and the process's parent issent a sigchld signal. 

status is returned to the parent process as the process's exit status and can be collected usi ng one of the watt fami ly of calls. 

RETURN VALUE 

exit never returns 

C0NF0RMST0 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

NOTES 

exit does not call any functions registered with the AN SI C atexit function and does not flush standard I/O buffers. To do 
th ese things, use exit(3). 
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SEE ALSO 

fork(2), execve(2), waitpid(2), wait4(2), kill(2), wait(3), exit(3) 


Linux, 21 July 1993 


accept 

accept- Accept a connection on a socket 

SYNOPSIS 

#include <sys/types.h> 

//include <sys/socket.h> 

int accept(int s, struct sockaddr *addr ,int*addrIen); 

DESCRIPTION 

The arguments is a socket that has been created with socket ( 2 ), bound to an address with bind( 2 ), and is listening for 
connections after aiisten( 2 ).The accept function extracts the first connection request on the queue of pending connec¬ 
tions, creates a new socket with the same properties of s, and allocates a new file descriptor for the socket. If no pending 
connections are present on the queue and the socket is not marked as nonblocking, accept blocks the caller until a connec¬ 
tion is present. If thesocket ismarked nonblocking and no pending connections are present on thequeue, accept returnsan 
error as described below. The accepted socket may not be used to accept more connections The original sockets remains 
open. 

The argument ad dr isa result parameter that is filled in with the address of the connecting entity, as known to the communi¬ 
cations layer. The exact format of theaddr parameter is determined by the domain in which the communication is occurring. 
The addr i en is a value-result parameter; it should initially contain the amount of space pointed to by add r; on return it will 
contain the actual length (in bytes) of the address returned. Thiscall isused with connection-based socket types currently 

With SOCK_STREAM. 

It is possible to select ( 2 ) a socket for the purposes of doing an accept by selecting it for read. 

For certain protocols that require an explicit confirmation, such as iso and datakit, accept can bethought of as merdy 
dequeuing the next connection request and not implying confirmation. Confirmation can be implied by a normal read or 
write on the new file descriptor, and rqection can be implied by closing the new socket. 

One can obtain user connection request data without confirming the connection by issuing a recvmsg( 2 ) call with amsg 
lovien of 0 and a nonzero msg controller!, or by issuing a getsockopt( 2 ) request. Similarly, one can provide user connection 
rqection information by issuingasendmsg( 2 ) call providing only the control information, or by calling setsockopt( 2 ). 

RETURN VALUES 

The call returns-i on error. If it succeeds, it returns a nonnegative integer that isa descriptor for the accepted socket. 

ERRORS 

EBADF 
ENOTSOCK 
EOPNOTSUPP 
EFAULT 
EWOULDBLOCK 

HISTORY 

The accept function appeared in BSD 4.2. 


The descriptor is invalid. 

The descriptor references a file not a socket. 

The referenced socket is not of type sock_stream. 

The addr parameter is not in a writable part of the user address space. 

The socket is marked nonblocking and no connections are present to be accepted. 



SEE ALSO 

bind(2), connect(2), listen(2), select(2), socket(2) 

BSD Man Page 24July 1993 


access 

access— C hecks user's permissions for a file 

SYNOPSIS 

#include <unistd.h> 

int access(const char *p at h n a me,intmod e); 

DESCRIPTION 

access checks whether the process would be allowed to read, write, or test for existence of thefile (or other file system object) 
whose name ispathname. If pathname isa symbolic link, permissions of the file referred by this symbolic link are tested, 
mode is a mask consisting of one or more of r_ok, w_ok, x_ok, and f_ok. 

r_ok, w_ok, and x_ok request checking whether the file exists and has read, write, and execute permissions, respectively. f_ok 
just requests checking for the existence of the file 

The tests depend on the permissions of the directories occurring in the path to thefile, as given in pathname, and on the 
permissions of directories and files referred by symbolic links encountered on the way. 

Thecheckisdonewith the process's real UID and GID, rather than with the effective I Dsasis done when actually 
attempting an operation. Thisisto allow sdt-U ID programs to easily determine the invoking user's authority. 

0 nly access bits are checked, not thefile type or contents. Therefore, if a directory is found to be "writable," it probably 
meansthat files can be created in the directory, and not that the directory can be written asafile Similarly, a DOSfilemay 
be found to be "executable," but the execve( 2 ) call will still fail. 

RETURN VALUE 

On success (all requested permissions granted), 0 is returned. On error (at least 1 bit in mode asked for a permission that is 
denied, or some other error occurred), -1 is returned and errno is set appropriately. 

ERRORS 

EACCES 

EFAULT 
EINVAL 

ENAMETOOLONG 
ENOENT 

ENOTDIR 
ENOMEM 
ELOOP 

RESTRICTIONS 

access returns an error if any of the access types in the requested call fails, even if other types might be successful, access may 
not work correctly on N FS file systems with UID mapping enabled because UID mapping is done on the server and hidden 
from the client, which checks permissions 


The requested access would be denied, either to the file itself or one of thedirectories in 

pat hname points outside your accessi ble address space, 
mode was incorrectly specified, 
pathname istOO long. 

A directory component in pathname would have been accessible but does not exist or was a 
dangling symbolic link. 

A component used as a directory in pathname isnot, in fact, a directory. 

I nsufficient kernel memory was available. 

pat hname contains a reference to a circular symbolic link, that is, a symbolic link containing 
a reference to itself. 
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CONFORMSTO 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

SEE ALSO 

stat(2), open(2), chmod(2), chown(2), setuid(2), setgid(2) 

Linux 1.2.13,17 March 1996 


acct 

acct— Switches process accounting on or off 

SYNOPSIS 

#include <unistd.h> 

int acct(const char ‘filename); 

DESCRIPTION 

Warning: Since thisfunction is not implemented as of Linux 0.99.11, it will always return -i and set errno to enosys. If 
acctkit is installed, the function performs as advertised. 

When called with the name of an existing file as argument, accounting is turned on and records for each terminating process 
are appended to f i i ename as it terminates. An argument of null causes accounting to be turned off. 

RETURN VALUE 

On success, 0 is returned. On error, -1 is returned and errno isset appropriately. 

NOTES 

No accounting is produced for programs running when a crash occurs. In particular, nonterminating processes are never 
accounted for. 

SEE ALSO 

acct(5) 

LinuxO.99.11,10Augustl993 


adjtimex 

adjtimex- Tunes kernel clock 

SYNOPSIS 

ffinclude <sys/timex.h> 

int adjtimexjstruct timex *buf); 

DESCRIPTION 

Linux uses David M ill’s clock adjustment algorithm, adjtimex reads and optionally sets adjustment parameters for this 
algorithm. 

adjtimex takes a pointer to a t i mex structure, updates kernel parameters from field values, and returns the same structure with 
current kernel values. This structure is declared as follows: 



adjtimex 






long offset; 
long frequency; 
long maxerror; 
long esterror; 

long time_constant; 
long precision; 
long tolerance; 

struct timeval time; 


mode selector */ 
time offset (usee) */ 
frequency offset (scaled ppm) */ 

estimated error (usee) */ 

clock command/status */ 

pll time constant */ 

clock precision (usee) (read only) */ 

clock frequency tolerance (ppm) 

(read only) */ 

(read only) */ 

usees between clock ticks */ 


The mode field determines which parameters, if any, to set. It may contain a bitwise-or combination of zero or more of the 
following bits: 

#define ADJ_OFFSET 0x0001 /* time o 

#define ADJ_FREQUENCY 0x 

#define ADJ_MAXERROR 0x 

#define ADJ_ESTERROR 0x 

tfdefine ADJ_STATUS 0x 

#define ADJ_TIMECONST 0x 

#define ADJ_TICK 0x 

#define ADJ_OFFSET_SINGLESHOT 0x 

0 rdinary users are restricted to a 0 value for mode. 0 nly the superuser may sdt any parameters 

RETURN VALUE 

On success adjtimex returns the value of but. status: 

#define TIME OK 0 /* clock synchronized */ 

#define TIME INS 1 /* insert leap second */ 

#define TIME DEL 2 /* delete leap second */ 

#define TIME OOP 3 /* leap second in progress */ 

#define TIME BAD 4 /* clock not synchronized */ 

0 n failure, adjtimex returns -i and sets errno. 

ERRORS 

efault but does not point to writable memory. 

eperm b uf. mode is nonzero and the user is not superuser. 

einval An attempt is made to set b u f. offset to a value outside the range-131071 to +131071, or 

to set buf. st at us to a value other than those listed above or to set but. ti ck to a value 
outside the range 900000/HZ to 1100000/HZ,where HZ isthe system timer interrupt 
frequency. 

SEE ALSO 

settimeofday(2) 


fset *1 

002 /* frequency offset */ 

004 /* maximum time error */ 

008 /* estimated time error */ 
010 /* clock status */ 

020 /* pll time constant */ 

000 /* tick value */ 

001 /* old-fashioned aditime */ 


Linux 1.2.4,15 April 1995 
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alarm 

alarm— Sets an alarm clock for delivery of a signal 

SYNOPSIS 

#include <unistd.h> 

unsigned int alarm(unsigned int seconds); 

DESCRIPTION 

alarm arranges for a sigalrm signal to be delivered to the process in seconds seconds 
If seconds ise, no new alarm isscheduled. 

In any event, any previously set alarm iscanceled. 

RETURN VALUE 

alarm returns the number of seconds remaining until any previously scheduled alarm was due to be delivered, or 0 if there 
wasno previously scheduled alarm. 

NOTES 

alarm and setitimer share the same timer; calls to one will interfere with use of the other. 

Scheduling delays can, as ever, cause the execution of the process to be delayed by an arbitrary amount of time 

C0NF0RMST0 

SVID, AT & T, PO SIX, X/O PEN , BSD 4.3 

SEE ALSO 

setitimer(2), signal(2), sigaction(2), gettimeofday(2), select(2), pause(2), sleep(3) 

Linux, 21 July 1993 


bdflush 

bdfiush— Starts, flushes, or tunes the buffer-dirty-flush daemon 

SYNOPSIS 

int bdflush(int fine, long ‘address); 
int bdflush(int func, long data); 

DESCRIPTION 

bdfiush starts, flushes, or tunes the buffer-dirty-flush daemon. Only the superuser may call bdfiush. 

If func is negative or 0 and no daemon has been started, bdfiush enters the daemon code and never returns. 

If f unc is 1, some dirty buffers are written to disk. 

If func is 2 or more and iseven (low bit is 0), address isthe address of a long word, and the tuning parameter numbered 
(f unc -2) 12 isreturned to the caller in that address. 

If func is 3 or more and isodd (low bit is 1), data is a long word and the kernel sets tuning parameter numbered |if|g-3)/2 
to that value. 

The set of parameters, their values, and their legal ranges are defined in the kernel source filef s/buffer. c. 




bind 




RETURN VALUE 

If func is negative or Band the daemon successfully starts, bdfiush never returns. Otherwise, the return value iso on success 
and -i on failure, with errno set to indicate the error. 

ERRORS 

eperm Caller is not superuser. 

e fault address points outside your accessible address space. 

ebusy An attempt was made to enter the daemon code after another process has already been 

entered. 

einval An attempt was madeto read or write an invalid parameter number, or to write an invalid 

value to a parameter. 

SEE ALSO 

fsync(2), sync(2), update(8), sync(8) 

Linux 1.2.4,15 April 1995 


bind 

bind— Bindsa name to a socket 

SYNOPSIS 

#include <sys/types.h> 

//include <sys/socket.h> 

int bind(int sockfd, struct sockaddr *my _ addr .intaddr I en); 

DESCRIPTION 

bind gives the socket, sockfd, the local address my.addr. my_addr isaddr i en bytes long. Traditionally, this iscalled assigning a 
nameto a socket. (When a socket is created with socket(2), it exists in a name space—an address family— but has no name 
assigned.) 

NOTES 

Binding a name in the UN IX domain creates a socket in the file system that must be deleted by the caller- using umink(2) 
- when it is no longer needed. 

The rules used in namebinding vary between communication domains. Consult the manual entries in section 4 for detailed 
information. 

RETURN VALUE 

On success, 0 is returned. On error, -1 is returned, and errno is set appropriately. 

ERRORS 

ebadf sockfd is not a valid descriptor. 

einval The socket is already bound to an address This may change in the future. Seeiinux/umx/ 

sock, c for details 

eacces T he address is protected and the user is not the superuser. 

Thefollowing errors are specific to UN IX domain (afjjnix) sockets 
einval addr en was wrong, or the socket was not in the afjjnix family. 

erofs Thesocketinodewould reside on a read-only file system. 

efault my.addr points outside your accessible address space. 
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ENAMETOOLONG my_addr iStOO long. 

enoent The file does not exist. 

enomem Insufficient kernel memory was available. 

enotdir A component of the path prefix is not a directory. 

eacces Search permission is denied on a component of the path prefix. 

eloop my_ a dd r contains a circular reference (that is, via a ^mbolic link). 

HISTORY 

The bind function call appeared in BSD 4.2. 

SEE ALSO 

accept(2), connect(2), listen(2), socket(2), getsockname(2) 

Linux0.99.11, 23July 1993 


brk, sbrk 

brk, sbrk— Change data segment size 

SYNOPSIS 

#include <unistd.h> 

int brk(void *end_data_segment ); 

void *sbrk(ptrdiff tincrement); 

DESCRIPTION 

brk sdtstheend of the data segment to the value specified byend.dat a. segment. 

end. data, segment must be greater than the end of the text segment and it must be 16KB before the end of the stack, 
sbrk increments the program'sdata space by increment bytes sbrk isn't a system call; it is just a C library wrapper. 

RETURN VALUE 

On success brk returns 0 , and sbrk returnsa pointer to the start of the new area. 0 n error, -i isreturned and errno issdtto 

ENOMEM. 

C0NF0RMST0 

BSD 4.3 

brk and sbrk are not defined in theC standard and are deliberately excluded from the PO SIX. 1 standard (see paragraphs 
B.1.1.1.3 and B.8.3.3). 

SEE ALSO 

execve(2), getrlimit(2), malloc(3), end(3) 

LinuxO.99.11, 21 July 1993 


cacheflush 

cachet lush— Flushes contents of the instruction and/or data cache 


SYNOPSIS 




DESCRIPTION 

cachet lush flushes contents of indicated cachets) for user addresses in the range addr to (addr+nbytes-i ). The cache may be 
one of the following: 

icache Flush the instruction cache. 

dcache W rite back to memory and invalidate the affected valid cache lines 

bcache Same as (icachei dcache). 

RETURN VALUE 

cachefiush returnso on successor -i on error. If errors are detected, errno will indicate the error. 

ERRORS 

einval T he cache parameter is not one of icache, dcache, or bcache. 

efault Someorall of the address range addr to (addr+nbytes- 1 ) is not accessible. 

BUGS 

The current implementation ignores the addr and nbytes parameters Therefore, the whole cache is always flushed. 

NOTE 

This system call is only availableon M I PS-based systems. 

SEE ALSO 

cachectl(2) 

Linux, 27 June95 

chdin,fchdir 

chdir, f chdir— C hanges the working directory 

SYNOPSIS 



DESCRIPTION 

chdir changesthe current directory to that specified in path. 

fchdir is identical to chdir, only the directory is given as an open file descriptor. 

RETURN VALUE 

On success 0 is returned. On error, -1 is returned, and errno is set appropriately. 

ERRORS 

Depending on the file system, other errors can be returned. The more general errors are listed here: 
eperm The process does not have execute permission on the di rectory. 

efault path points outside your accessible address space. 

ENAMETOOLONG path istOO long. 
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EBADF 

ENOENT 

ENOMEM 

ENOTDIR 

EACCES 

ELOOP 

SEE ALSO 

getcwd(3), chroot(2) 


fd is not a valid file descriptor. 

The file does not exist. 

I nsufficient kernel memory was available. 

A component of the path prefix is not a directory. 

Search permission is denied on a component of the path prefix, 
path contains a circular reference (that is, via a symbolic link) 


Linux 1.2.4,15 April 1995 


chmod,fchmod 

chmod, f chmod- C hanges permissions of a file 

SYNOPSIS 

#include <sys/types.h> 

//include <sys/stat.h> 

int chmod(const char *path,modetmode); 

int fchmod(int tildes .modetmode); 


DESCRIPTION 

The mode of the file given by path or referenced by 1 1 1 edes ischanged. 


M odes are specified by oring thefollowing: 


S_ISUID 

S_ISGID 

S_ISVTX 

S_IRUSR (S_IREAD) 
S_IWUSR (s_iwrite) 

S_IXUSR (S_I EXEC) 

S_IRGRP 

S_IWGRP 

S_IXGRP 

S_IROTH 

S_IWOTH 

S_IXOTH 


04000 Set user ID on execution 
02000 Set group ID on execution 
01000 Sticky bit 
00400 Read by owner 
00200 W rite by owner 
00100 Executesearch by owner 
00040 Read by group 
00020 W rite by group 
00010 Executesearch by group 
00004 Read by others 
00002 W rite by others 
00001 Executtfsearch by others 

T he effective UID of the process must be 0 or must match the owner of the file. 
TheeffectiveU ID orGID must be appropriate for setting execution bits 
D epending on thefile system, set user ID and set group ID execution bits may be turned 
off if a file is written. On some file systems, only the superuser can sdt the sticky bit, which 
may havea special meaning (that is, for directories a file can only be deleted by the owner 
or the superuser). 


RETURN VALUE 

0 n success 0 is returned. O n error, -1 is returned and emno issdt appropriately. 
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ERRORS 

D epending on thefile system, other errors can be returned. The more general errors for chmod are listed here 


EPERM 

EROFS 

EFAULT 

ENAMETOOLONG 

ENOENT 

ENOMEM 

ENOTDIR 

EACCES 

ELOOP 


The effective UID does not match the owner of the fi le and is not 0. 
The named file resides on a read-only file system, 
path points outside your accessible address space, 
path is too long. 

The file does not exist. 

I nsufficient kernel memory was available. 

A component of the path prefix is not a directory. 

Search permission is denied on a component of the path prefix, 
path contains a circular reference (that is, via a symbolic link) 


The general errors for f chmod are listed here: 

ebadf Thedescriptorisnotvalue. 

enoent See above 

eperm See above 

erofs See above 


SEE ALSO 

open(2), chown(2), stat(2) 


Linux 0.99.11, 21 July 1993 


chown, fchown 

chown, fchown- C hanges ownership of a file 

SYNOPSIS 

#include <sys/types.h> 

//include <unistd.h> 

int chown(const char ‘path, uid t owner, gid_t group); 
int fchown(int fd, uid t owner, gid_t group); 

DESCRIPTION 

The owner of thefile specified bypath or by f d is changed. Only the superuser may change the owner of a file. The owner of 
a file may change the group of the file to any group of which that owner is a member. The superuser may change the group 
arbitrarily. 

If the owner or group is specified as-i, that ID is not changed. 

RETURN VALUE 

0 n success, 0 is returned. 0 n error, -1 is returned and ermo issdt appropriately. 

ERRORS 

D epending on thefile system, other errors can be returned. The more general errors for chown are listed here 
eperm The effective UID does not match the owner of thefile, and is not 0; or the owner or group 

were specified incorrectly. 

erofs The named file resides on a read-only file system. 

efault path points outside your accessible address space. 
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ENAMETOOLONG path istOO long. 

enoent The file does not exist. 

enomem Insufficient kernel memory was available. 

enotdir A component of the path prefix is not a directory. 

eacces Search permission is denied on a component of the path prefix. 

eloop path contains a circular reference (that is, via a symbolic link). 

The general errors for fchown are listed here: 

ebadf Thedescriptorisnotvalue. 

enoent See above 

eperm See above 

erofs See above 

NOTES 

chown does not follow symbolic links The prototype for fchown is only available if use bsd isdefined. 

SEE ALSO 

chmod(2), flock(2) 

Linux 0.99.11, 21 July 1993 

chroot 


chroot— C hanges root directory 

SYNOPSIS 



DESCRIPTION 

chroot changes the root directory to that specified in path. This directory will be used for pathnames beginning with /.The 
root directory is inherited by all children of the current process. 

0 nly the superuser may change the root directory. 

Note that this call does not change the current working directory, so that. can be outside the tree rooted at/. 

RETURN VALUE 

0 n success 0 is returned. 0 n error, -1 is returned and errno issdt appropriately. 

ERRORS 

Depending on the file system, other errors can be returned. The more general errors are listed here: 
eperm T he effective UID does not match the owner of the file, and is not 0; or the owner or group 

were specified incorrectly. 

erofs Thenamed file resides on a read-only file system. 

efault path pointsoutsideyouraccessibleaddressspace. 

ENAMETOOLONG pat h iStOO long. 

enoent The file does not exist. 

enomem Insufficient kernel memory was available. 



done 


0 


ENOTDIR 

EACCES 

ELOOP 

SEE ALSO 

chdir( 2 ) 


clone 

clone- Creates a child process 

SYNOPSIS 

#include <linux/sched.h> 

#include <linux/unistd.h> 

pid t clone(void *sp, unsigned long flags); 

DESCRIPTION 

clone isan alternate interface to fork, with more options fork is equivalent to cione(0, sigcldicopyvm). 

If s p is nonzero, the child process uses s p as its initial stack pointer. 

The low byte of f i a g s containsthesignal sent to the parent when the child dies flags may also be bitwise ored with either or 
both of copyvm and copyfd. 

If copyvm isset, child pages are copy-on-write images of the parent pages. If copyvm isnot set, the child process shares the same 
pages as the parent, and both parent and child may write on thesamedata. 

If copyfd isset, thechild'sfile descriptors are copies of the parent'sfile descriptors If copyfd isnot set, the chi Id’s file 
descriptors are shared with the parent. 

RETURN VALUE 

On success the PID of the child process is returned in the parent's thread of execution, and 0 is returned in the child's 
thread of execution. On failure a -1 will be returned in the parent's context, no child process will be created, and errno will 
be set appropriately. 

ERRORS 

enosys clone will always return thiserror, unless your kernel was compiled with 

clone_actually_works_ok defined. 

eagain fork cannot allocate sufficient memory to copy the parent's page tables and allocate a task 

structure for the child. 

BUGS 

By default, clone_actually_works_ok isnot defined. 

There is no entry for clone in /nb/iibc.so.4.5.26. 

Comments in the kernel as of 1.1.46 indicate that it mishandles the case where copyvm isnot set. 


A component of the path prefix is not a directory. 

Search permission is denied on a component of the path prefix, 
path contains a circular reference (that is, via a symbolic link) 


Linux 1.1.46, 21 August 1994 


SEE ALSO 

fork( 2 ) 


Linux 1.2.9,10 Junel995 



Part II: System Calls 


752 


close 

close— C loses a file descri ptor 

SYNOPSIS 

#include <unistd.h> 
int close(int f d); 

DESCRIPTION 

close closes a file descriptor so that it no longer refers to any file and may be reused. Any locks held on the file it was 
associated with, and owned by the process, are removed (regardless of the file descriptor that was used to obtain the lock). 

If f d is the last copy of a particular file descriptor, the resources associ ated with it are freed; if the descriptor was the last 
reference to a file that has been removed using unlink, the file is deleted. 

RETURN VALUE 

close returns 0 on success, or -1 if an error occurred. 

ERRORS 

ebadf fd isn't a valid open file descriptor. 

C0NF0RMST0 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

NOTES 

Not checking the return value of close isacommon but nevertheless serious programming error. Filesystem implementa¬ 
tions that use techniques as write-behind to increase performance may lead to wr i t e (2) succeeding, although the data has not 
been written yet. T he error status may be reported at a later write operation, but it is guaranteed to be reported on closing 
the file. Not checking the return value when closing the file may lead to silent loss of data. This can especially be observed 
with N FS and disk quotas 

SEE ALSO 

open(2), fcntl(2), shutdown(2), unlink(2), fclose(3) 

14 April 1996 


connect 

connect— Initiates a connection on a socket 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/socket.h> 

int connectfint sockfd, struct sockaddr *serv_addr .intaddrIen); 

DESCRIPTION 

The parameter sockfd is a socket. If it isof type sock_dgram, this call specifies the peer with which thesocket is to be 
associated; this address is that to which datagrams are to be sent, and theonly address from which datagrams are to be 
received. If thesocket isof type sock_stream, this call attempts to make a connection to another socket. The other socket is 



dup, dup2 


0 


specified by serv_addr, which is an address in the communications space of the socket. Each communications space interprets 
the serv_addr, parameter in its own way. G enerally, stream sockets may successfully connect only once; datagram sockets 
may use connect multiple times to change their association. Datagram sockets may dissolve the association by connecting to 
an invalid address, such as a null address. 

RETURN VALUE 

If the connection or binding succeeds, 0 isreturned. On error, -1 is returned and errno is set appropriately. 

ERRORS 

SeetheLinux kernel source code for details 

HISTORY 

The connect function call first appeared in BSD 4.2. 

SEE ALSO 

accept(2), bind(2), listen(2), socket(2), getsockname(2) 

Linux0.99.11, 23July 1993 


dup,dup2 

dup, dup2— D uplicate a file descriptor 

SYNOPSIS 

#include <unistd.h> 
int dup(int oldfd); 
int dup2(int oldfd,intnewfd); 

DESCRIPTION 

dup and dup2 create a copy of the file descriptor 01 df d . 

The old and new descriptors can be used interchangeably. They share locks, file position pointers and flags for example if 
thefile position is modified by using lseek on one of the descriptors the position isalso changed for the other. 

Thetwo descriptors do not share the dose-on-exec flag, however, 
dup uses the lowest-numbered unused descriptor for the new descriptor. 
dup2 makesne»fd bethecopyofoi dfd, closing newt d first if necessary. 

RETURN VALUE 

dup and dup2 return the new descriptor, or -1 if an error occurred (in which case errno is set appropriately). 

ERRORS 

ebadf oi df d isn't an open file descriptor, or newf d is out of the allowed range for fi le descriptors 

emfile T he process already has the maximum number of file descriptors open and tried to open a 

new one. 

WARNING 

The error returned bydup2 is different from that returned by f cnti (..., f_dupfd ,...) when newf d is out of range On some 
systems dup2 also sometimes returns einval like f_dupfd. 
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CONFORMSTO 

SVID.AT&T, POSIX,X/OPEN, BSD 4.3 

SEE ALSO 

fcntl(2), open(2), close(2). 

Linux 1.1.46,21 August 1994 


execve 

execve— Execute program 

SYNOPSIS 

#include <unistd.h> 

int execve (const char ‘filename, const char *arg« [], const char *e n v p [ ]); 

DESCRIPTION 

execve o executes the program pointed to by f i i ename. fi i ename must be either a binary executable or a shell script starting 
With a line in the format#! interpreter [arg], 

execve o doesnot return on success, and the text, data, bss, and stack of the calling process are overwritten by that of the 
program loaded. The program invoked inherits the calling process's PI D, and any open file descriptorsthat are not set to 
doseon exec. Signals pending on the parent process are cleared. 

If the current program is being ptraced, a sigtrap issentto it after a successful execveo. 

RETURN VALUE 

On success, execveo doesnot return; on error -i is returned and errno isset appropriately. 

ERRORS 

EACCES 
EACCES 
EPERM 
EPERM 
E 2 BIG 
ENOEXEC 
EFAULT 

ENAMETOOLONG 
ENOENT 
ENOMEM 
ENOTDIR 
EACCES 
ELOOP 

CONFORMSTO 

SVID, AT & T, PO SIX, X/O PEN , BSD 4.3 

NOTES 

SUID andSGID processes can not be pt reced'd SUID or SGI D. 


The file is not a regular file 
Execute permission isdenied forthefile 
Thefilesystem ismounted noexec. 

Thefile system ismounted nosui d and thefile has an SUID orSGID bit set. 
Theargument list istoo big. 

The magic number in thefile is incorrect, 
f i i ename pointsoutsideyour accessible address space, 
fi I ename iStOO long. 

The file does not exist. 

I nsufficient kernel memory was available. 

A component of the path prefix is not a directory. 

Search permission isdenied on a component of the path prefix, 
f i i ename contains a circular reference (that is, via a symbolic link). 
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A maximum line length of 127 characters is allowed for the first line in a#! executable shell script. This may be circum¬ 
vented by changing the max size of buf, in which case you will become bound by the 1024 byte size of a buffer, which is not 
easily worked around. 

SEE ALSO 

execl(3), fork(2) 

Linux 1.1.46, 21 August 1994 


fcntl 

fcnti —M anipulate file descriptor 

SYNOPSIS 

#include <unistd.h> 

#include <fcntl.h> 

int fcntl(int fd,intcmd); 

int fcntl(int f d,intcmd,longar g); 


DESCRIPTION 


fcnti performs one of various miscellaneous operations on fd. The operation in question isdetermined bycmd: 


F_DUPFD 


F_GETFD 

F_SETFD 

F_GETFL 

F_SETFL 


F_GETLK, F_SETLK, 

and f_setlkw 

F_GETLK 

F_SETLK 

F_SETLKW 

F_GET0WN 

F_SET0WN 


M akes a r g be a copy of f d , closing f d first if necessary. 

The same functionality can be more eas'ly achieved by using dup2(2). 

The old and new descriptors may be used interchangeably. They share locks, file position 
pointers, and flags; for example if the file position ismodified by using lseek on one of the 
descriptors, the position is also changed for the other. 

Thetwo descriptors do not share the close-on-exec flag, however. 

0 n success, the new descriptor is returned. 

Read the dose-on-exec flag. If the low-order bit isO, the file will remain open across exec; 
otherwise it will be closed. 

Sdt the close-on-exec flag to the value specified by arg (only the least significant bit 
is used). 

Read the descriptor's flags (all flags- asset by open(2)— are returned), 
set the descriptor's flags to the value specified by a r g. 

0 nly o_append and o_nonblock may be set. 

The flags are shared between copies (made with dup and so on) of the same file descriptor. 
Theflagsand their semantics are described in open(2). 

M anage discretionary file locks The third argument arg is a pointer to a struct flock 
(that may be overwritten by thiscall). 

Return theflock structure that prevents us from obtaining the lock, or set the i type field of 
the lock to fjjnlck if there is no obstruction. 

The lock isset (when l type is f_rdlck or f_wrlck) or cleared (when it is fjjnlck). 

If the lock is held by someone else thiscall returns -i and setsermo to eacces or eagain. 
Like f_setlk, but instead of returning an error, we wait for the lock to be released. 

G et the process ID (or process group) of the owner of a socket. 

Process groups are returned as negative values 
Set the processor process group that owns a socket. 

For these commands, ownership means receiving sigio or sig-urg signals 
Process groups are specified using negative values 
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RETURN VALUE 

The return value depends on the operation: 
fjxjpfd The new descriptor. 

f_getfd Value of flag. 

f_getfl Value of flags. 

f_getown Value of descriptor owner. 

On error, -i is returned and errno is set appropriately. 

ERRORS 

ebadf f d is not an open file descriptor. 

einval For f_dupfd, arg is negative or isgreater than the maximum allowable value. 

emfile For f_dupfd, the process already hasthe maximum number of file descriptors open. 

NOTES 

T he errors returned by dup2 are different from those returned by f_dupfd. 

C0NF0RMST0 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

SEE ALSO 

dup2(2), open(2), socket(2). 

Linux, 26 September 1995 


fdatasync 

fdatasync— Synchronizes a file's in-core data with that on disk 

SYNOPSIS 

#include <unistd.h> 

#ifdef POSIX SYNCHRONIZED 10 
int fdatasync(int f d); 

#endif 

DESCRIPTION 

fdatasync flushes all data buffers of a file to disk (before the system call returns). It resembles f sync but is not required to 
update the metadata such as access ti me 

Applications that access databases or log files often write a tiny data fragment (for example onelinein alogfile) and then 
call fsync immediately in order to ensure that the written data is physically stored on the hard disk. Unfortunately, fsync will 
always initiate two write operations: one for the newly written data and another one in order to update the modification time 
stored in the inode. If the modification time is not a part ofthetransaction concept fdatasync can be used to avoid 
unnecessary inode disk write operations 

RETURN VALUE 

On success 0 is returned. On error, -1 is returned and errno isset appropriately. 




flock 
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ERRORS 

ebadf fd is not a valid filedescriptor open for writing. 

erofs, einval fd is bound to a special file which does not support synchronization. 

eio An error occurred during synchronization. 

BUGS 

Currently (Linux 1.3.86) fdatasync is equivalent to fsync. 

C0NF0RMST0 

POSIX.4 


SEE ALSO 

fsync(2), B.O. Gallmeister, POSIX.4 ,0 'Reilly, pp. 220-223,343. 


Linux 1.3.86,13 April 1996 


flock 

flock— Applies or removes an advisory lock on an open file 

SYNOPSIS 

ffinclude <sys/file.h> 

int flock(int fd.intoperation); 

DESCRIPTION 

Apply or remove an advisory lock on an open file. The file is specified by fd. Valid operations are given here 
lock_sh Shared lock. M ore than one process may hold a shared lock for a given file at a given time 

lock_ex Exclusive lock. 0 nly one process may hold an exclusive lock for a given file at a given time 

lockjjn Unlock. 

lock_nb Don't block when locking. M ay be specified (by oring) along with one of the other 

operations. 

A single file may not have both shared and exclusive locks A file is locked (that is the 
inode), not the file descriptor. So, dup(2) and fork(2) do not create multiple instances 
of a lock. 

RETURN VALUE 

On success 0 is returned. On error, -1 is returned and errno isset appropriately. 

ERRORS 

ewouldblock Thefile is locked and theLOCK_NB flag was selected. 

NOTES 

Under Linux, flock isimplemented asacall to fcnti. Please see fcnti(2) for more details on errors 

SEE ALSO 

open(2), close(2), dup(2), execve(2), fcntl(2), fork(2) 


Linux 0.99.11, 22 July 1993 
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fork,vfork 

fork, vfork— Creates a chi Id process 

SYNOPSIS 

#include <unistd.h> 
pid t fork(void); 
pid t vfork(void); 

DESCRIPTION 

fork creates a child process that differs from the parent process only in its PID and P PID, and in the fact that resource 
utilizations are set to 0 . File locks and pending signals are not inherited. 

Under Linux, fork is implemented using copy-on-write pages, so the only penalties incurred by fork are the time and 
memory required to duplicate the parent's page tables and to create a unique task structure for the child. 

RETURN VALUE 

On success, the PID of the child process is returned in the parent's thread of execution, and ao is returned in the child's 
thread of execution. On failure a -1 will be returned in the parent's context, no child process will be created, and errno will 
be set appropriately. 

ERRORS 

eagain fork cannot allocate sufficient memory to copy the parent's page tables and allocate a task 

structure for the child. 

BUGS 

Under Linux, vfork is merely an alias for fork, fork never returns the error enomem. 

C0NF0RMST0 

SVID, AT & T, PO SIX, X/O PEN , BSD 4.3 

SEE ALSO 

clone(2), execve(2), wait(2) 

Linux 1.2.9,10 Junel995 


fsync 

fsync— Synchronizes a file's complete in-core state with that on disk 

SYNOPSIS 

#include <unistd.h> 
int fsync(int f d); 

DESCRIPTION 

fsync copies all in-core parts of a file to disk. 

In some applications, fdatasync isa more efficient alternative to fsync. 

RETURN VALUE 

0 n success, 0 is returned. 0 n error, -1 is returned and errno isset appropriately. 



ggdents 


759 


ERRORS 

EBADF 

EROFS, EINVAL 
EIO 


f d is not a valid file descriptor open for writing, 
f d is bound to a special file that does not support synchronization. 
An error occurred during synchronization. 


C0NF0RMST0 

POSlX.lb 

SEE ALSO 

bdflush(2), fdatasync(2), sync(2), update(8), sync(8) 


Linux 1.3.85,13 April 1996 


getdents 

getdents- Gets directory entries 

SYNOPSIS 

#include <unistd.h> 

#include <linux/dirent.h> 

#include <linux/unistd.h> 

syscall3(int, getdents, uint, fd, struct dirent *, dirp, uint, count); 
int getdents(unsigned int fd, struct dirent *d i r p , unsigned int count); 

DESCRIPTION 

getdents reads several di rent structures from the directory pointed at by f d into the memory area pointed to by di r p. The 
parameter count is the size of the memory area. 

Thedi rent structure is declared asfollows 

i 

unsigned short d_reclen; 
char d_name [NAME_MAX+1] 

} 

d.i no isan inodenumber. d_ of f is the distance from the start of the directory to the start of the next di rent. d_ r ec i en isthe 
size of this entire di rent, d _ n a me is a null-terminated filename 
Thiscall supersedes readdir(2). 

RETURN VALUE 

On success, the number of bytes read is returned. On end of directory, a is returned. On error, -i is returned and errno is set 
appropriately. 

ERRORS 

ebadf Invalid filedescriptor f d. 

enotdir File descriptor does not refer to a directory. 

SEE ALSO 

readdir(2), readdir(3) 


/* inode number */ 

I* offset to next dirent */ 

/* length of this dirent */ 

/* file name (null-terminated) */ 


Linux 1.3.6,22 July 1995 




Part II: System Calls 


760 

getdomainname, setdomainname 

getdomainname, setdomainname —GetS^SetS domain name 

SYNOPSIS 

#include <unistd.h> 

int getdomainname(char 'name, size_t len); 
int setdomainname(const chan 'name, size_t len); 

DESCRIPTION 

These functions are used to access or to change the domain name of the current processor. 

RETURN VALUE 

On success, 0 is returned. On error, -1 is returned and errno isset appropriately. 

ERRORS 

EINVAL For getdomainname, name pointsto NULL Or name is longer than len. 

eperm For setdomainname, the caller was not the superuser. 

EINVAL For setdomainname, I en Was tOO long. 

C0NF0RMST0 

POSIX does not specify these calls 

BUGS 

getdomainname is not compliant with other implementations because they always return 1 en bytes, even if name is longer. 

Linux, however, returns einval in thiscase(asof D LL 4.4.1 libraries). 

NOTES 

Under Linux, getdomainname is implemented at the library level by calling uname(2). 

SEE ALSO 

gethostname(2), sethostname(2), uname(2) 

Linux0.99.11, 22 July 1993 


getdtablesize 

getdtabiesize- Gets descriptor table size 

SYNOPSIS 

#include <unistd.h> 
int getdtablesize(void); 

DESCRIPTION 

getdtabiesize returns themaximum number of filesa process can have open. 

NOTES 

getdtabiesize isimplemented asa library function in DLL 4.4.1. Thisfunction returns open jiax (set to 256 in Linux 
0.99.11) if open_max was defined when the library was compiled. Otherwise, -1 isreturned and errno isset to enosys. 




gdtyoups, sdtg-oups 




SEE ALSO 

close(2), dup(2), open(2) 


Linux0.99.11, 22 July 1993 


getgid,getegid 

getgid, getegid- Gets group identity 

SYNOPSIS 

#include <unistd.h> 
gid_t getgid(void); 
gid_t getegid(void); 

DESCRIPTION 

getgid returns the real group ID of the current process 
getegid returns the effective group ID of the current process. 

Thereal ID correspondstothelD of thecalling process The effective ID correspondsto theset ID bit on thefile being 
executed. 


ERRORS 

T hese functions are always successful. 

C0NF0RMST0 

POSIX, BSD 4.3 

SEE ALSO 

setregid(2), setgid(2) 

Linux0.99.11, 23July 1993 


getgroups,setgroups 

getgroups, setgroups— Gdt^SetS group access list 

SYNOPSIS 

#include <unistd.h> 

int getgroups(int size, gid_t list[]); 

#define_USE_BSD 
#include <grp.h> 

int setgroups(size_t size, const gid_t ‘list ); 

DESCRIPTION 

getgroups Up to si ze supplemental groups are returned in i i st . If si ze Is 0 , 1 i st is not modified, but 

the total number of supplemental groups for the process is returned. 

Setsthesupplemental groups for the process. Only thesuperuser may usethisfunction. 


setgroups 
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RETURN VALUE 

getgroups 

setgroups 

ERRORS 

EFAULT 
EPERM 
EINVAL 

C0NF0RMST0 

getgroups conforms to POSIX.1 (and ispresent in BSD 4.3). Since setgroups requires privilege it is not covered under 
POSIX.1. 

BUGS 

The use bsd flag probably shouldn't be required for setgroups. 

SEE ALSO 

initgroups(3) 

Linux0.99.11, 23July 1993 


On success, the number of groups stored in list is returned (if si ze iso, however, the 
number of supplemental group ID s associated with the process is returned). On error, -i is 
returned and errno is set appropriately. 

On success, o is returned. On error, -i is returned and errno isset appropriately. 

list has an invalid address. 

For setgroups, the user is not the superuser. 

For setgroups, gi dset size is greater than ngroups (32 for Linux 0.99.11). 



gethostid,sethostid 

gethosttd, sethostid- G ds/sets the unique identifier of the current host 

SYNOPSIS 

#include <unistd.h> 

long int gethostid(void); 
int sethostid(long int hostid); 

DESCRIPTION 

Get or set a unique 32-bit identifier for the current machine. The 32-bit identifier is intended to be unique among all UNIX 
systemsin existence. This normally resembles the Internet address for the local machine as returned bygethostbyname(3), 
and thus usually never needs to be set. 

The sethostid call is restricted to the superuser. 

Thehost i d argument isstored in thefile /etc/hostid. 

RETURN VALUES 

gethostid returns the 32-bit identifier for the current host asset by sethostid(2). 

C0NF0RMST0 

POSIX.1 does not define these functions, but ISO/IEC 9945-1:1990 mentionsthem in B.4.4.1. 

FILES 


/etc/hostid 
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SEE ALSO 

hostid(l), gethostbyname(3) 


Linux0.99.13, 29 November 1993 


gethostname,sethostname 

gethostname, sethostname— G etS/SdtS hostname 

SYNOPSIS 

#include <unistd.h> 

int gethostname(char ‘name, size_t len); 
int sethostname(const char ‘name, size_t len); 

DESCRIPTION 

T hese functions are used to access or to change the hostname of the current processor. 

RETURN VALUE 

On success, 0 is returned. On error, -1 is returned and errno isset appropriately. 

ERRORS 

einval 1 en is negative or, for sethostname, larger than the maximum allowed size For gethostname 

on Linux/i386,1 en issmaller than the actual size. 
eperm For sethostname, the caller was not the superuser. 

efault name isan invalid address. 

C0NF0RMST0 

POSIX.1 does not define these functions, but ISO/I EC 9945-1:1990 mentionsthem in B.4.4.1. 

BUGS 

Some other implementations of gethostname successfully return 1 en bytes even if name is longer. Linux/Alpha complies with 
thisbehavior. Linux/i386, however, returns einval in this case (as of DLL 4.6.27 libraries). 

NOTES 

Under Linux/Alpha, gethostname isasystem call. Under Linux/i386, gethostname isimplemented at the library level by 
Calling uname(2). 

SEE ALSO 

getdomainname(2), setdomainname(2), uname(2) 

Linux 1.3.6, 22 July 1995 


getitimen,setitimer 

getitimer, setitimer—Gdtsfsets value of an interval timer 

SYNOPSIS 

#include <sys/time.h> 

int getitimer(int which, struct itimerval ‘value); 

int setitimer(int whi ch .conststruct itimer-val ‘value, struct itimerval ‘ovalue); 
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DESCRIPTION 

The system provides each process with three interval timers, each decrementing in a distinct timedomain. When any timer 
expires, a signal issent to the process, and the timer (potentially) restarts 
itimefmieal Decrementsin real time and delivers sigalrm upon expiration. 

itimer_virtual D ecrements only when the process is executing, and delivers si gvtalrm upon expiration. 

itimer_prof D ecrements both when the process executes and when the system is executing on behalf of 

the process Coupled with itimer_virtual, this timer is usually used to profile the time 
spent by the application in user and kernel space, sigprof isddivered upon expiration. 

Timer values are defined by the following structures 

struct itimerval { 

struct timeval it_interval; /* next value */ 
struct timeval it_value; /* current value */ 

}; 

struct timeval { 

long tv_sec; /* seconds */ 

long tv_usec; /* microseconds */ 

}; 

getitimer(2) fills the structure indicated by v a i u e with the current setting for the timer indicated bywhi ch (one of 
itimer_real, itimer_virtual, or itimer_prof). The element it_vaiue is set to the amount of time remaining on the timer, or 
0 if the timer is disabled. Similarly, it_intervai issetto the reset value. setitimer(2) sdts the indicated timer to the value in 
v a i ue. If oval ue is nonzero, the old value of the timer is stored there. 

Timers decrement from i t.vai ue to 0, generate a signal, and reset to it.i ntervai . A timer that issetto 0 (i t _vai ue is 0 or the 
timer expires and i t j ntervai is®) stops. 

Both tv. sec and tv. usee are significant in determining the duration of a timer. 

Timers will never expire before the requested time, instead expiring some short, constant time afterward, dependent on the 
system timer resolution (currently 10ms). Upon expiration, a signal will be generated and the timer reset. If thetimer expires 
while the process is active (always true for itimer_virt), the signal will beddivered immediatdy when generated. Otherwise 
the ddivery will be offset by a small time dependent on the system loading. 

RETURN VALUE 

0 n success, 0 is returned. 0 n error, -1 is returned and errno issdt appropriatdy. 

ERRORS 

EFAULT 

einval 

SEE ALSO 

gettimeofday(2), sigaction(2), signal(2) 

BUGS 

Under Linux, the generation and ddivery of a signal are distinct and there each signal is permitted only one outstanding 
event. It’s therefore coned vable that under pathologically heavy loading, itimer_real will expire before the signal from a 
previous expiration has been ddivered. Thesecond signal in such an event will be lost. 


vai ue and oval ue are not valid pointers 

which is not one of itimer_real, itimer_virt, or itimer_prof. 


Linux0.99.11, 5 August 1993 
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getpagesize 

getpagesize— Gets system page size 

SYNOPSIS 

#include <unistd.h> 
size_t getpagesize(void); 

DESCRIPTION 

Returnsthe number of bytes in apage. This is the system's page size, which isnot necessarily thesameasthe hardware page 
size. 


NOTES 

getpagesize is implemented as a library function in DLL 4.4.1. Depending on what is defined when the library iscompiled, 
thisfunction returns exec_pagesize (set to 4096 in Linux 0.99.11), nbpg (set to 4096 in Linux 0.99.11), or nbpc (not defined in 
Linux 0.99.11 or D LL 4.4.1 libraries). 

SEE ALSO 

sbrk(2) 

LinuxO.99.11, 23July 1993 


getpeername 

getpeername- G ets the name of the connected peer 

SYNOPSIS 

int getpeername(int s, struct sockaddr ‘name,int*n a me I en); 

DESCRIPTION 

getpeername returns the name of the peer connected to sockets. Thenamei en parameter should be initialized to indicate the 
amount of space pointed to byname. On return it contains the actual size of the name returned (in bytes). Thenameis 
truncated if the buffer provided istoo small. 

RETURN VALUE 

On success, 0 is returned. On error, -1 is returned and errno isset appropriately. 

ERRORS 

ebadf Thearguments is not a valid descriptor. 

enotsock Thearguments isafile, not a socket. 

enotconn Thesocket isnot connected. 

enobufs Insufficient resources were available in thesystem to perform theoperation. 

efault The name parameter points to memory not in a valid part of the process address space 

HISTORY 

The getpeername function call appeared in BSD 4.2. 

SEE ALSO 

accept(2), bind(2), getsockname(2) 


BSD Man Page 24July 1993 
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getpid, getppid 

getpid, getppid— G ets process identification 

SYNOPSIS 

#include <unistd.h> 
pid_t getpid(void); 
pid_t getppid(void); 

DESCRIPTION 

getpid returns the process ID of the current process. (Thisisoften used by routines that generate unique temporary 
filenames.) 

getppid returnsthe process ID of the parent of the current process. 

C0NF0RMST0 

POSIX, BSD 4.3, SVID 

SEE ALSO 

exec(2), fork(2), kill(2), mkstemp(3), tmpnam(3), tempnam(3), tmpfile(3) 

Linux0.99.11, 23 July 1993 


getpriority, setpnionity 

getpriority, setpriority— Gets/sdts program scheduling priority 

SYNOPSIS 

#include <sys/time.h> 

#include <sys/resource.h> 

int getpriority(int which,int who); 

int setpriority(int which,int who,int prio); 

DESCRIPTION 

The scheduling priority of the process, process group, or user, as indicated by whi ch and who, is obtained with the getpriority 
call and set with thesetpriority call, whi ch isoneof prioj’rocess, PRio_PGRP,or priojjser, and who is interpreted relative to 
whi ch (a process identifier for prio_process, process group identifier for prio_pgrp, and a user ID for priojjser). A 0 value of 
who denotes the current process, process group, or user, prio isa value in the range-20 to 20. The default priority is 0; lower 
priorities cause more favorable scheduling. 

The getpriority call returns the highest priority (lowest numerical value) enjoyed by any of the specified processes. The 
setprionty call sets the priorities of all the specified processes to the specified value. Only the superuser may lower priorities. 

RETURN VALUES 

Because getpriority can legitimately return the value-1, it is necessary to clear the external variable errno prior to the call, 
and then check it afterward to determine whether a-1 is an error or a legitimate value. Thesetpriority call returns 0 if there 
is no error, or-1 if there is. 

ERRORS 

esrch N 0 process was located using thewhi ch and who values specified. 

einval which was not one of prio_process, prio_pgrp, or priojjser. 



getrlimit, getrusage, astrlimit 




In addition to these errors, setprionty will fail with thefollowing: 

eperm A process was located, but neither its effective nor real user ID matched the effective user ID 

of the caller. 

eacces A nonsuperuser attempted to lower a process priority. 

HISTORY 

These function callsappeared in BSD 4.2. 

SEE ALSO 

nice(l), fork(2), renice(8) 

BSD Man Page 24July 1993 


getrlimit,getrusage,setrlimit 

getrlimit, getrusage, setrlimit— Get/set resource limits and usage 

SYNOPSIS 

#include <sys/time.h> 

#include <sys/resource.h> 

#include <unistd.h> 

int getrlimit (int resource, struct rlimit *rI i m) ; 

int getrusage (int who, struct rusage "usage); 

int setrlimit (int resource, const struct rlimit *rlim); 

DESCRIPTION 

getrlimit and setrlimit get and set resource limits resource should be one of thefollowing: 

RLIMIT CPU /* CPU time in seconds */ 

RLIMIT FSIZE /* Maximum filesize */ 

RLIMIT DATA /* max data size */ 

RLIMIT STACK /* max stack size */ 

RLIMIT CORE /* max core file size */ 

RLIMIT RSS /* max resident set size */ 

RLIMIT NPROC /* max number of processes */ 

RLIMIT NOFILE /* max number of open files */ 

RLIMIT MEMLOCK /* max locked-in-memory address space*/ 

A resource may be unlimited if you set the limit to rlim_infinity. rlimit_ofile is the BSD name for rlimit_nofile. 
The rlimit structure isdefined as follows : 
struct rlimit 
{ 

int rlim_cur; 
int rlim_max; 


getrusage returns the current resource usagesfor awho of either rusage_self or rusage_children: 
struct rusage 
{ 

struct timeval ru_utime; /* user time used */ 
struct timeval ru_stime; /* system time used */ 
long ru_maxrss; /* maximum resident set size */ 

long ru_ixrss; /* integral shared memory size */ 
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long rujninflt; 
long ru_majflt; 
long ru_nswap; 
long nu_inblock; 
long ru_oublock; 
long ru_msgsnd; 
long rujnsgrcv; 
long nu_nsignals; 

long ru_nivcsw; 


/* integral unshared data size */ 
/* integral unshared stack size */ 
/* page reclaims */ 

/* page faults */ 

/* block input operations */ 

/* block output operations */ 


/* messages received */ 

/* voluntary context switches */ 

/* involuntary context switches */ 


RETURN VALUE 

0 n success, 0 is returned. 0 n error, -1 is returned and errno issdt appropriately. 

ERRORS 

EINVAL getrlimit Or setrlimit iSCalled With a bad resource, getrusage iSCalled With a bad who. 

eperm A nonsuperuser tries to use setrlimit 0 to increase the soft or hard limit above the current 

hard limit, or a superuser tries to increase rlimit_nofile above the current kernel maximum. 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

ulimit(2), quota(2) 

Linux, 23July 1993 


getsid 

getsid- Gets session ID 

SYNOPSIS 

#include <unistd.h> 

DESCRIPTION 

getsid (0 ) returns the session ID of thecalling process, getsid(p) returnsthesession ID of the process with processID p. 

ERRORS 

On error, -i will be returned. The only error that can happen isESRCH, when no processwith processID p wasfound. 

C0NF0RMST0 

Thiscall is Linux specific. 

SEE ALSO 

setsid(2) 


Linux 1.3.85,11 April 1996 
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getsockname 

getsockname— G ets socket name 

SYNOPSIS 

int getsockname(int s ", struct sockaddr *" name ", int *" namelen ); 

DESCRIPTION 

getsockname returns the current name for the specified socket. Thenamei en parameter should be initialized to indicate the 
amount of space pointed to byname. On return it contains the actual size of the name returned (in bytes). 

RETURN VALUE 

0 n success, 0 is returned. 0 n error, -1 is returned and errno isset appropriately. 

ERRORS 

ebadf Thearguments is not a valid descriptor. 

enotsock Thearguments is a file, not a socket. 

enobufs Insufficient resources were available in the system to perform the operation. 

efault T he n a me parameter points to memory not in a valid part of the process address space 

HISTORY 

The getsockname function call appeared in BSD 4.2. 

BUGS 

Names bound to sockets in the UN IX domain are inaccessible; getsockname returns a 0-length name. 

SEE ALSO 

bind(2), socket(2) 

BSD Man Page 24July 1993 


getsockopt,setsockopt 

getsockopt, setsockopt— G et and set options on sockets 

SYNOPSIS 

#include <sys/types.h> 

//include <sys/socket.h> 

int getsockopt(int s ,inti eveI ,intoptname,void*opt val ,int*optIen); 
int setsockopt(int s ,irrtl evel , intopt n a me, const void *opt val , into pt I e n); 

DESCRIPTION 

getsockopt and setsockopt manipulate theo pt i ons associated with a socket. Options may exist at multiple protocol levels; 
they are always present at the uppermost socket level. 

When manipulating socket options, the level at which the option resides and the name of the option must be specified. To 
manipulate options at the socket level, 1 evei is specified assoL_socKET. To manipulate options at any other level, the protocol 
number of the appropriate protocol controlling the option issupplied. For example to indicate that an option is to be 
interpreted bytheTCP protocol, level should be set to the protocol number of TCP; seegetprotoent(3). 
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The parameters opt vai and opt i on are used to access option values for setsockopt. For getsockopt they identify a buffer in 
which the value for the requested option(s) is to be returned. For getsockopt, opt i en is a value-result parameter, initially 
containing thesize of the buffer pointed to by optvai , and modified on return to indicate the actual size of the value 
returned. If no option value is to be supplied or returned, optvai may be null. 

opt name and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The 
include file <sys/$ ocket. h> contains definitionsfor socket-level options, described below. Options at other protocol levels 
vary in format and name; consult the appropriate entries in section 4 of the manual. 

Most socket-level options utilize an i nt parameter for optvai . For setsockopt, the parameter should be nonzero to enable a 
boolean option, or 0 if the option is to be disabled. so_linger uses a struct Unger parameter, defined in <i i nux/socket. h>, 
which specifies the desired state of the option and the linger interval (see below). so_sndtimeo and so_rcvtimeo use a struct 
timevai parameter, defined in <sys/ti me. h>. 


Thefollowing options are recognized at the socket level. Except as noted, each may be examined with getsockopt and set 
With setsockopt: 


S0_DEBUG 

SO_REUSEADDR 

SO_KEEPALIVE 

S0_D0NTR0UTE 

SO_LINGER 

S0_BR0ADCAST 

S0_00BINLINE 

S0_SNDBUF 

S0_RCVBUF 

SO_SNDLOWAT 

S0_RCVL0WAT 

S0_SNDTIME0 

S0_RCVTIME0 

S0_TYPE 

SO_ERROR 


Enables recording of debugging information. 

E nables local address reuse. 

Enables keep connections alive 

Enables routing bypass for outgoing messages 

Linger on close if data present. 

Enables permission to transmit broadcast messages 
Enables reception of out-of-band data in band. 

Sets buffer size for output. 

Sets buffer size for input. 

Sets minimum count for output. 

Sdts minimum count for input. 

Sets time-out value for output. 

Sdts time-out value for input. 

G ets the type of the socket (get only). 

Gets and clears error on the socket (get only). 


so_debug enables debugging in the underlying protocol modules. 

so_reuseaddr indicates that the rules used in validating addresses supplied in a bind(2) call should allow reuse of local 
addresses 


so_keepalive enables the periodic transmission of messages on a connected socket. Should the connected party fail to 
respond to these messages the connection is considered broken and processes using the socket are notified viaasiGPiPE 
signal when attempting to send data. 

so_dontroute indicates that outgoing messages should bypass the standard routing facilities Instead, messages are directed to 
the appropriate network interface according to the network portion of the destination address. 
so_linger controls the action taken when unsent messages are queued on socket and aciose(2) is performed. If the socket 
promises reliable delivery of data and so_linger isset, the system will block the process on the close attempt until it is able to 
transmit the data or until it decides it isunableto deliver the information (a time-out period, termed the linger interval, is 
specified in the setsockopt call when so_linger is requested). If so_linger isdisabled and a close is issued, the system will 
process the close in a manner that allows the process to continue as quickly as possible. 

Thei i nger structure is defined in <i i nux/socket. h> as follows: 
struct linger { 

int l_onoff; /* Linger active */ 

int l_linger; /* How long to linger for */ 



gdtsxkopt, £tsockopt 




i_onoff indicates whether to linger. If it isset to i, i_unger containsthetimein hundredths of seconds how long the process 
should linger to complete thedose If i_onoff isset to 0, the process returns immediately. 

Theoption so_broadcast requests permission to send broadcast datagrams on thesocket. Broadcast wasa privileged 
operation in earlier versionsof the system. With protocolsthat support out-of-band data, the so_oobinline option requests 
that out-of-band data be placed in the normal data input queue as received; it will then be accessible with recv or read calls 
without the msg_oob flag. Some protocols always behave as if this option is set. 

so_sndbuf and so_rcvbuf are options to adjust the normal buffer sizes allocated for output and input buffers, respectively. The 
buffer size may be increased for high-volume connections or may be decreased to limit the possible backlog of incoming data. 
Thesystem places an absolute limit on these values 

so_sndlowat isan option to sdt the minimum count for output operations. M ost output operations process all of the data 
supplied by the call, delivering data to the protocol for transmission and blocking as necessary for flow control. Nonblocking 
output operations will process as much data as permitted subject to flow control without blocking, but will process no data if 
flow control does not allow the smaller of the low water mark value or the entire request to be processed. A seiect(2) 
operation testing the ability to write to a socket will return true only if the low water mark amount could be processed. The 
default value for so_sndlowat isset to a convenient size for network efficiency, often 1024 . 
so_rcvlowat isan option to sdt the minimum count for input operations. In general, receive calls will block until any 
(nonzero) amount of data is received, then return with thesmalleroftheamountavailableortheamount requested. The 
default value for so_rcvlowat is 1. If so_rcvlowat is set to a larger value blocking receive calls normally wait until they have 
received the smaller of the low water mark value or the requested amount. Receive calls may still return less than the low 
watermark if an error occurs, a signal is caught, or the type of data next in the receive queue is different than that returned. 
so_sndtimeo isan option to set a time-out value for output operations It accepts a struct timevai parameter with the 
number of seconds and microseconds used to limit waits for output operationsto complete If a send operation has blocked 
for this much time it returns with a partial count or with the error ewouldblock if no data were sent. I n the current 
implementation, this timer is restarted each time additional data are delivered to the protocol, implying that the limit applies 
to output portions ranging in size from the low water mark to the high water mark for output. 

so_rcvtimeo isan option to sdt a time-out value for input operations It accepts a st r net timevai parameter with the number 
of seconds and microseconds used to limit waits for input operationsto complete In the current implementation, this timer 
is restarted each time additional data are received by the protocol, and thus the limit is in effect an inactivity timer. Ifa 
receive operation has been blocked for this much time without receiving additional data, it returns with a short count or with 
the error ewouldblock if no data were received. 

Finally, so_type and so_error are options used only with setsockopt. 

so_type returns the type of the socket, such assocK_STREAM; it is useful for servers that inherit sockets on startup. 
so_error returnsany pending error on thesocket and clears the error status. It may be used to check for asynchronous errors 
on connected datagram sockets or for other asynchronous errors. 

RETURN VALUE 

0 n success, 0 is returned. 0 n error, -1 is returned and err™ isset appropriately. 

ERRORS 

ebadf Thearguments is not a valid descriptor. 

enotsock Thearguments is a file, not a socket. 

enoprotoopt Theoption is unknown at the level indicated. 

efault Theaddress pointed to by opt vai is not in a valid part of the process address space For 

getsockopt, this error may also be returned if optlen isnotin avalid part of the process 
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HISTORY 

These system calls appeared in BSD 4.2. 

BUGS 

Several of the socket options should be handled at lower levels of the system. 

SEE ALSO 

ioctl(2), socket(2), getprotoent(3), protocols(5) 

BSD Man Page, 22 April 1996 


gettimeofday, settimeofday 

gettimeofday, settimeof day— Get/ set time 

SYNOPSIS 

#include <sys/time.h> 

#include <unistd.h> 

int gettimeofday(struct timeval ‘tv, struct timezone *tz); 

int settimeofday(const struct timeval *t* , const struct timezone *tz); 

DESCRIPTION 

gettimeofday and settimeof day Can set the time as well asa timezone t V isa timeval struct, as specified in /usr/include/ 

sys/time.h: 

struct timeval { 

long tv_sec; /* seconds */ 

long tv_usec; /* microseconds */ 


and tz is a timezone: 
struct timezone { 


/* minutes west of Greenwich */ 
int tz_dsttime; 

/* type of dst correction */ 


with daylight savings times defined asfollows 


DST_N0NE /* 

DSTJJSA 
DST_AUST 
DST_WET 
DST_MET 
DST_EET 
DST_CAN 
DST_GB 
DST_RUM 
DST_TUR 
DST_AUSTALT 


USA style dst */ 

Australian style dst */ 
Western European dst */ 
Middle European dst */ 
Eastern European dst */ 
Canada */ 

Great Britain and Eire */ 
Rumania */ 

Australian style with shift 


in 1986 */ 





getuid, geteuid 




And thefollowing macros are defined to operate on this: 

#define timerisset(tvp) \ 

((tvp)->tv_sec !! (tvp)->tv_usec) 

#define timercmp(tvp, uvp, cmp)\ 

((tvp)->tv_sec cmp (uvp)->tv_sec ||\ 

(tvp)->tv_sec == (uvp)->tv_sec &&\ 

(tvp)->tv_usec cmp (uvp)->tv_usec) 

#define timerclear(tvp) 

((tvp)->tv_sec = (tvp)->tv_usec = 0) 

If either t v or t z isnull.thecorrespondingstructureisnot set or returned. 

Only the superuser can use setttmeofday. 

ERRORS 

eperm setttmeofday is called by someone other than the superuser. 

einval Time zone (or something else) isinvalid. 

C0NF0RMST0 

BSD 4.3 


SEE ALSO 

date(l), adjtimex(2), time(2), ctime(3), ftime(3) 


Linux 1.2.4,15 April 1995 


getuid,geteuid 

getutd, geteuid— G Pt user identity 

SYNOPSIS 

#include <unistd.h> 
uid_t geteuid(void); 

DESCRIPTION 

getuid returns the real user ID of thecurrent process 
geteuid returns the effective user ID of the current process 

Thereal ID correspondstothelD of thecalling process The effective ID correspondstothesetID bit on thefile being 
executed. 


ERRORS 

T hese functions are always successful. 

C0NF0RMST0 

POSIX, BSD 4.3 

SEE ALSO 

setreuid(2), setuid(2) 


Linux0.99.11, 23 July 1993 
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idle 

idle- M akes process 0 idle 

SYNOPSIS 

#include <unistd.h> 
void idle(void); 

DESCRIPTION 

idle isan internal system call used during bootstrap. It marks the process's pages as swappable lowers its priority, and enters 
the main scheduling loop, idle never returns. 

0 nly process 0 may call idle. Any user process, even a process with superuser permission, will receive eperm. 

RETURN VALUE 

idle never rdturnsfor process 0, and always returns-i for a user process 

ERRORS 

eperm Always, for a user process 

Linux 1.1.46, 21 August 1994 


ioctl 

iocti— Controls devices 

SYNOPSIS 

#include <sys/ioctl.h> 

int ioctl(int d ,intr equest , ...); 

(The "third" argument istraditionally char *a r gp and will be so named for this discussion.) 

DESCRIPTION 

The iocti function manipulates the underlying device parameters of special files. In particular, many operating characters 
tics of character special files (for example, terminals) may be controlled with iocti requests. The argument d must be an open 
filedescriptor. 

An iocti request has encoded in it whether the argument is an i n parameter or out parameter, and the size of the argument 
ar gp in bytes M acros and defines used in specifying an iocti request are located in the file <sys/ i octi. h>. 

RETURN VALUE 

0 n success 0 is returned. 0 n error, -1 is returned and errno issdt appropriately. 

ERRORS 

EBADF 
ENOTTY 
ENOTTY 
EINVAL 

HISTORY 

An iocti function call appeared in version 7 AT&T UN IX. 


d is not a valid descriptor, 
d is not associated with a character special device 

The specified request does not apply to the kind of object that the descriptor d references, 
request Or ar gp isnot Valid. 



SEE ALSO 

execve(2), fcntl(2), mt(4), sd(4), tty(4) 

INTRODUCTION 

Thisisiocti List 1.3.27, a list of iocti calls in Linux/i386 kernel 1.3.27. It contains 421 ioctisfrom /usr/inciude/ 
fasm, linuxg/* .h. For each iocti, you'll find the numerical value name, and argument type. 

An argument type of const struct too * meansthe argument is input to the kernel, struct too * meansthe kernel outputs 
the argument. If the kernel uses the argument for both input and output, this is marked with // i-o. 

Some ioctis take more arguments or return more values than a single structure. These are marked // more and are docu¬ 
mented further in a separate section. 

T his list is incomplete 11 does not include 

■ ioctis defined internal to the kernel (scsi iocti. h). 

■ ioctis defined in modules distributed separately from the kernel. 

And, of course, I may have errors and omissions. 

Please email changes and comments to mec@duracef.shout.net. I am particularly interested in loadable modules that define 
their own ioctis If you know of such a module tell me where I can ftp it, and I'll include its ioctis in my next release. 

MAIN TABLE 


: -Sf?pI ude/asm- i 386 / socket. h> 

0X00008901 FIOSETOWN 

0X00008902 SIOCSPGRP 

0X00008903 FIOGETOWN 

0X00008904 SIOCGPGRP 

0X00008905 SIOCATMARK 

0x00008906 SIOCGSTAMP 









timeval * 


0x00005401 

0x00005402 

0x00005403 

0x00005404 

0X00005405 

0X00005406 

0X00005407 

0X00005408 

0X00005409 

0X0000540A 

0X0000540B 

0X0000540C 

0X0000540D 

0X0000540E 

0X0000540F 

0x00005410 


TCGETS 

TCSETS 

TCSETSW 

TCSETSF 

TCGETA 

TCSETA 

TCSETAW 

TCSETAF 

TCSBRK 

TCXONC 

TCFLSH 

TIOCEXCL 

TIOCNXCL 

TIOCSCTTY 

TIOCGPGRP 

TIOCSPGRP 



const struct termio * 

const struct termio * 

const struct termio * 

int 

int 

int 


int 

pid_t * 
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TIOCOUTQ 

TIOCSTI 

TIOCGWINSZ 

TIOCSWINSZ 

TIOCMGET 



TIOCINQ 

TIOCLINUX 


TIOCGSERIAL 

TIOCSSERIAL 

TIOCPKT 

FIONBIO 

TIOCNOTTY 

TIOCSETD 

TIOCGETD 

TCSBRKP 

TIOCTTYGSTRUCT 

FIONCLEX 

FIOCLEX 

FIOASYNC 

TIOCSERCONFIG 

TIOCSERGWILD 

TIOCSERSWILD 

TIOCGLCKTRMIOS 

TIOCSLCKTRMIOS 

TIOCSERGSTRUCT 

TIOCSERGETLSR 

TIOCSERGETMULTI 

TIOCSERSETMULTI 




0X000089E0 SI0CAX25GETUID const struct sockaddr_ax25 
0X000089E1 SI0CAX25ADDUID const struct sockaddr_ax25 
0X000089E2 SI0CAX25DELUID const struct sockaddr_ax25 
0X000089E3 SI0CAX25N0UID const int * 
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0x00435901 

0x00435902 

0x00435903 

0x00435904 

0x00435905 

0x00435906 

0X00435907 

0x00435908 

0x00435909 


<i ncl ude/1 i nux/ext2 fs.h> 
0x80046601 
0x40046602 
0X80047601 
0x40047602 


CYGETMON 

CYGETTHRESH 

CYSETTHRESH 

CYGETDEFTHRESH 

CYSETDEFTHRESH 

CYGETTIMEOUT 

CYSETTIMEOUT 

CYGETDEFTIMEOUT 

CYSETDEFTIMEOUT 


EXT2_I0C_GETFLAGS 
EXT 2_IOC_SETF LAGS 
EXT2_I0C_GETVERSI0N 
EXT2_I0C_SETVERSI0N 


cycladesjnonitor * 




0X00000000 

0X00000001 

0X00000002 

0X00000003 



0X0000001B 
0X0000001C 
0X0000001E 
0X00000028 


FDCLRPRM 

FDSETPRM 

FDDEFPRM 

FDGETPRM 

FDMSGON 

FDMSGOFF 

FDFMTBEG 

FDFMTTRK 

FDFMTEND 

FDSETEMSGTRESH 

FDFLUSH 

FDSETMAXERRS 

FDGETMAXERRS 

FDGETDRVTYP 

FDSETDRVPRM 

FDGETDRVPRM 

FDGETDRVSTAT 

FDPOLLDRVSTAT 

FDRESET 

FDGETFDCSTAT 

FDWERRORCLR 

FDWERRORGET 

FDRAWCMD 

FDTWADDLE 


const struct floppy_struct * 
const struct floppy_struct * 
struct floppy_struct * 


const struct format_descr * 




const struct floppy_max_errors * 
struct floppy_max_errors * 
struct f char [16]; g * 
const struct floppy_drive_params * 
struct floppy_drive_params * 
struct floppy_drive_struct * 
struct floppy_drive_struct * 
int 

struct floppy_fdc_state * 

struct floppy_write_errors * 
struct floppy_raw_cmd * // MORE // 1-0 























0X000089F0 


SIOCDEVPLIP 
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0X40086D01 
0x801C6D02 
0X80046D03 
0X80206D04 
0X40206D05 


MTIOCTOP 

MTIOCGET 

MTIOCPOS 

MTIOCGETCONFIG 

MTIOCSETCONFIG 


const struct mtop * 

struct mtconfiginfo * 
const struct mtconfiginfo * 


0X000089E0 


0X000089E2 

0X000089E3 


<i ncl ude/1 i nux/ sbpcd. h> 
0x00009000 
0x00005382 


0X00005470 

0X00005471 

0x00005472 

0x00005473 

0x00005474 


SIOCNRGETPARMS 

SIOCNRSETPARMS 

SIOCNRDECOBS 

SIOCNRRTCTL 


DDIOCSDBG 

CDROMAUDIOBUFSIZ 


TIOCSCCINI 

TIOCCHANINI 

TIOCGKISS 

TIOCSKISS 

TIOCSCCSTAT 


struct nr_parms_struct * // 1-0 
const struct nr_parms_struct * 



const struct sccjnodem * 
struct ioctl_command * // 1-0 
const struct ioctl_command * 
struct scc_stat * 


0x00005382 

0x00005383 

0x00005384 

0x00005385 


SCSI_IOCTL_GET_IDLUN 
SCSI_IOCTL_TAGGED_ENABLE 
SCSI_IOCTL_TAGGED_DISABLE 
SCSI_IOCTL_P ROBE_HOST 


const int * // MORE 


SMB_IOC_GETMOUNTUID 



SIOCADDRT 

SIOCDELRT 

SIOCGIFNAME 

SIOCSIFLINK 

SIOCGIFCONF 

SIOCGIFFLAGS 

SIOCSIFFLAGS 


const struct rtentry * // MORE 
const struct rtentry * // MORE 


struct ifconf * // MORE // 1-0 
struct ifreq * II 1-0 
const struct ifreq * 









ioctl 


783 


0x00008915 

0x00008916 

0x00008917 


0x00008919 
0x0000891 A 


UX/: 

1x0000510( 
1X0000510- 
0XC08C5102 
0XC0045103 
0x80045104 
0x80045105 
0x40045106 


SIOCGIFADDR 

SIOCSIFADDR 

SIOCGIFDSTADDR 

SIOCSIFDSTADDR 

SIOCGIFBRDADDR 

SIOCSIFBRDADDR 

SIOCGIFNETMASK 

SIOCSIFNETMASK 

SIOCGIFMETRIC 

SIOCSIFMETRIC 

SIOCGIFMEM 

SIOCSIFMEM 

SIOCGIFMTU 

SIOCSIFMTU 

OLD SIOCGIFHWADDR 

SIOCSIFHWADDR 

SIOCGIFENCAP 

SIOCSIFENCAP 

SIOCGIFHWADDR 

SIOCGIFSLAVE 

SIOCSIFSLAVE 

SIOCADDMULTI 

SIOCDELMULTI 

SIOCADDRTOLD 

SIOCDELRTOLD 

SIOCDARP 

SIOCGARP 

SIOCSARP 

SIOCDRARP 

SIOCGRARP 

SIOCSRARP 

SIOCGIFMAP 

SIOCSIFMAP 


SNDCTL_SEQ_R ESET 

SNDCTL_SEQ_SYNC 

SNDCTL_SYNTH_INFO 

SNDCTL_SEQ_CTRLRATE 

SNDCTL_SEQ_GETOUTCOUNT 

SNDCTL_SEQ_GETINCOUNT 

SNDCTL_SEQ_P ERCMODE 


ct ifreq *111 
t struct ifreq 
ct ifreq *111 
t struct ifreq 
ct ifreq *111 
t struct ifreq 


const struct ifreq * 
const struct ifreq * 


const struct arpreq * 
struct arpreq * // 1-0 
const struct arpreq * 
const struct arpreq * 
struct arpreq * II 1-0 
const struct arpreq * 

const struct ifreq * 



struct synth_info * // 1-0 
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0x40285107 
0x40045108 
0x40045109 
0x8004510A 
0x8004510B 
0XC074510C 
0x4004510D 
0XC004510E 
0x4004510F 


0x40085112 

0XC0045401 

0X00005402 

0X00005403 

0X00005404 

0XC0045405 

0XC0045406 

0x40045407 

0x40045408 

0XCFB85001 

0XC0046D00 

0XC0046D01 

0XC0216D02 

0x00005000 

0X00005001 

0XC0045002 

0XC0045003 

0XC0045004 

0XC0045006 

0XC0045007 

0x00005008 

0XC0045009 

0XC004500A 

0X8004500B 

0XC0045005 

0X800C500C 

0X800C500D 

0X0000500E 

0x80045002 

0x80045006 

0x80045005 


SNDCTL FM LOAD INSTR 

SNDCTL_SEQ_TESTMIDI 

SNDCTL_SEQ_RESETSAMPLES 

SNDCTL_SEQ_NRSYNTHS 

SNDCTL_SEQ_NRMIDIS 

SNDCTL_MIDI_INFO 

SNDCTL_SEQ_THRESHOLD 

SNDCTL_SYNTH_MEMAVL 

SNDCTL_FM_40P_ENABLE 

SNDCTL_PMGR_ACCESS 

SNDCTL_SEQ_PANIC 

SNDCTL_SEQ_OUTOFBAND 

SNDCTL_TMR_TIMEBASE 

SNDCTL_TMR_START 

SNDCTL_TMR_ST OP 

SNDCTL_TMR_CONTINUE 

SNDCTL_TMR_TEMPO 

SNDCTL_TMR_SOURCE 

SNDCTL_TMR_METRONOME 

SNDCTL_TMR_SELECT 

SNDCTL_PM6R_IFACE 

SNDCTL_MIDI_PRETIME 

SNDCTL_MIDI_MPUMODE 

SNDCTL_MIDI_M PUCMD 

SNDCTL_DSP_RESET 

SNDCTL_DSP_SYNC 

SNDCTL_DSP_SPEED 

SNDCTL_DSP_STEREO 

SNDCTL_DSP_GETBLKSIZE 

SOUND_PCM_WRITE CHANNELS 

SOUND_PCM_WRITE FILTER 

SNDCTL_DSP_POST 

SNDCTL_DSP_SUBDIVIDE 

SNDCTL_DSP_SETFRAGMENT 

SNDCTL_DSP_GETFMTS 

SNDCTL_DSP_SETFMT 

SNDCTL_DSP_GETOSPACE 

SNDCTL_DSP_GETISPACE 

SNDCTL_DSP_NONBLOCK 

SOUND_PCM_READ RATE 

SOUND_PCM_READ CHANNELS 

SOUND_PCM_READ BITS 


const struct sbi_instrument * 


const int * 
int * 
int * 


const int * 
int * // 1-0 


const int * 

struct patmgr_info * // 1-0 


const struct seq_event_rec * 
int * // 1-0 


int * // 1-0 
int * // 1-0 
const int * 


int * // I-0 


struct patmgr_info * // 1-0 
int * II I-0 


struct mpu_command_rec * // 1-0 


int * // I-0 
int * II I-0 



struct audio-buf-info * 
struct audio-buf-info * 
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0x80045007 
0X00004300 
0XCFB04301 
0XC0144302 
0XC0144303 
0x40144304 
0X40144305 
0XC0144306 
0XC0144307 
0X4FA44308 
0X8FA44309 
0X80044D00 
0X80044D01 
0X80044D02 
0X80044D03 
0X80044D04 
0X80044D05 
0X80044D06 
0X80044D07 
0X80044D08 
0X80044D09 
0X80044D0A 
0X80044D0B 
0X80044D0C 
0X80044D0D 
0X80044D0E 
0X80044D0F 
0X80044D10 
0X80044D1C 
0X80044D1D 
0X80044D1E 
0X80044DFF 
0X80044DFE 
0X80044DFD 
0X80044DFB 
0X80044DFC 
0XC0044D00 
0XC0044D01 
0XC0044D02 
0XC0044D03 
0XC0044D04 
0XC0044D05 


SOUND_PCM_READ FILTER 

SNDCTL_COPR_RESET 

SNDCTL_COPR_LOAD 

SNDCTL_COPR_RDATA 

SNDCTL_COPR_RCODE 

SNDCTL_COPR_WDATA 

SNDCTL_COPR_WCODE 

SNDCTL_COPR_RUN 

SNDCTL_COPR_HALT 

SNDCTL_COPR_SENDMSG 

SNDCTL_COPR_RCVMSG 

SOUND_MIXER_READ_VOLUME 

SOUND_MIXER_READ_BASS 

SOUND_MIXER_READ_TREBLE 

SOUND_MIXER_READ_SYNTH 

SOUND_MIXER_READ_PCM 

SOUND_MIXER_READ_SPEAKER 

SOUND_MIXER_READ_LINE 

SOUND_MIXER_READ_MIC 

SOUND_MIXER_READ_CD 

SOUND_MIXER_READ_IMIX 

SOUND_MIXER_READ_ALTPCM 

SOUND_MIXER_READ_RECLEV 

SOUND_MIXER_READ_IGAIN 

SOUND_MIXER_READ_OGAIN 

S0UND_MIXER_READ_LINE1 

S0UND_MIXER_READ_LINE2 

S0UND_MIXER_READ_LINE3 

SOUND_MIXER_READ_MUTE 

SOUND_MIXER_READ_ENHANCE 

SOUND_MIXER_READ_LOUD 

SOUND_MIXER_READ_RECSRC 

SOUND_MIXER_READ_DEVMASK 

SOUND_MIXER_READ_RECMASK 

SOUND_MIXER_READ_STEREODEVS 

SOUND_MIXER_READ_CAPS 

SOUND_MIXER_WRITE_VOLUME 

SOUND_MIXER_WRITE_BASS 

SOUND_MIXER_WRITE_TREBLE 

SOUND_MIXER_WRITE_SYNTH 

SOUND_MIXER_WRITE_PCM 

SOUND_MIXER_WRITE_SPEAKER 


int * 


const struct copr_buffer * 

struct copr_debug_buf * // 1-0 

struct copr_debug_buf * II 1-0 

const struct copr_debug_buf * 

const struct copr_debug_buf * 

struct copr_debug_buf * // 1-0 

struct copr_debug_buf * // 1-0 

const struct coprjnsg * 

struct coprjnsg * 

int * 

int * 

int * 

int * 

int * 

int * 

int * 


int 

int 

int 


int 

int 

int 

int 

int 

int 
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0XC0044D06 
0XC0044D07 
0XC0044D08 
0XC0044D09 
0XC0044D0A 
0XC0044D0B 
0XC0044D0C 
0XC0044D0D 
0XC0044D0E 
0XC0044D0F 
0XC0044D10 
0XC0044D1C 
0XC0044D1D 
0XC0044D1E 
0XC0044DFF 


SOUND_M 

SOUND_M 

SOUND_M 

SOUND_M 

SOUND_M 

SOUND_M 

SOUND_M 

SOUND_M 

SOUND_M 

SOUND_M 

SOUND_M 

SOUND_M 

SOUND_M 

SOUND_M 

SOUND_M 


XER_WRITE_LINE 

XER_WRITE_MIC 

XER_WRITE_CD 

XER_WRITE_IMIX 

XER_WRITE_ALTPCM 

XER_WRITE_RECLEV 

XER_WRITE_IGAIN 

XER_WRITE_OGAIN 

XER_WRITE_LINE1 

XER_WRITE_LINE2 

XER_WRITE_LINE3 

XER_WRITE_MUTE 

XER_WRITE_ENHANCE 

XER_WRITE_LOUD 

XER_WRITE_RECSRC 



0X0000560A 


UMSDOS_READDIR_DOS 

UMSDOS_UNLINK_DOS 

UMSDOS_RMDIR_DOS 

UMSDOS_STAT_DOS 

UMSDOS_CREAT_EMD 

UMSDOS_UNLINK_EMD 

UMSDOS_READDIR_EMD 

UMSDOS_GETVERSION 

UMSDOS_INIT_EMD 

UMSDOS_DOS_SETUP 

UMSDOS_RENAME_DOS 


VT_OPENQRY 

VT_GETMODE 

VT_SETMODE 

VT_GETSTATE 

VT_SENDSIG 

VT_RELDISP 

VT_ACTIVATE 

VT_WAI TACTI VE 

VT_DISALLOCATE 

VT_RESIZE 

VT_RESIZEX 


struct umsdos_ioctl * // 1-0 
const struct umsdos_ioctl * 
const struct umsdos_ioctl * 
struct urasdos_ioctl * // 1-0 
const struct umsdos_ioctl * 
const struct umsdos_ioctl * 
struct umsdos_ioctl * // 1-0 
struct umsdos_ioctl * 

const struct umsdos_ioctl * 
const struct umsdos_ioctl * 


int * 

struct vt_mode * 


int 

int 

int 

int 


const struct vt_consize * 
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MORE ARGUMENTS 

Some ioctis take a pointer to a structure that contains additional pointers These are documented herein alphabetical order. 
cdromreadaudio takes an input pointer const struct cdrom read audio *. The but field points to an output buffer of length 
nframes * CD FRAMESIZE RAW. 


CDROMREADCOOKED, CDR0MREADM0DE1, CDR0MREADM0DE2, and CDROM-READRAW take an input pointer const Struct cdrom msf *.They 

use the same pointer as an output pointer to char n. The length varies by request. Foccdromreadmodei, most drivers use 


cd_framesize, but the optics storage dri 


iver uses opt blocksize instead (both have the numerical value 2048). 


CDROMREADCOOKED 

CDROMREADMODE1 

CDR0MREADM0DE2 

CDROMREADRAW 


CD_FRAMESIZE] 
CD_FRAMESIZE or OPT 
CD_FRAMESIZE_RAW0] 
CD_FRAMESIZE_RAW] 


BLOCKSIZE] 


EQL_ENSLAVE, EQL_EMANCIPATE, EQL_GETSLAVECFG, EQL_SETSLAVECFG, EQL_GETMASTERCFG, and EQL_SETMASTERCFG take a Struct 

ifreq *.Theifr data field is a pointer to another structure asfollows: 


EQL_ENSLAVE 

EQL_EMANCIPATE 

EQL_GETSLAVECFG 

EQL_SETSLAVECFG 

EQL_GETMASTERCFG 

EQL_SETMASTERCFG 


const struct slaving_request 
const struct slaving_request 
struct slave_config * // 1-0 
const struct slave_config * 
struct master_config * 
const struct master_config * 


fdrawcmd takes a struct floppy raw cmd *. If flags & fd raw write is nonzero, then data pointsto an input buffer of length 
length. If flags & fd raw read is nonzero, then data pointsto an output buffer of length length. 

GIO_FONTX and PI0_F0NTX take a struct console font desc ‘Oraconst struct console_font_desc *, respectively. chardata 
pointsto a buffer of char [charcount]. This is an output buffer for gio_fontx and an input buffer for pio_fontx. 

GIO_UNIMAP and PIO_UNIMAP take a struct unlmapdesc ‘ora const struct unimapdesc *, respectively. entries pointstoa 
buffer of struct unipair [entry ct]. This is an output buffer for giojjnimap and an input buffer for piojjnimap. 
kdaddio, kddelio, kddisabio, and kdenabio enable or disable access to I/O ports They are essentially alternate interfaces to 

ioperm. 


kdmapdisp and kdunmapdisp enable or disable memory mappings or I/O port access They are not implemented in the kernel. 
scsi_ioctl_probe_host takes an input pointer const int *, which is a length. It uses the same pointer asan output pointer to 
a char n buffer of this length. 

siocaddrt and siocdelrt take an input pointer whose type depends on the protocol: 

M OSt protocols const struct rtentry * 

AX.25 const struct ax25_route * 

NET/ROM const struct nr_route_struct * 


siocgifconf takes a struct ifconf *.Theifc but field pointsto a buffer of length itc ten bytes, into which the kernel writes 
a list Of type struct ifreq []. 

siocsifhwaddr takes an input pointer whose type depends on the protocol: 

M OSt protocols const struct ifreq * 

AX.25 const char [AX25_ADDR_LEN] 


tioclinux takes a const char *. It usesthisto distinguish several independent subcases. In the following table n + too means 
too after an N-byte pad. struct selection isimplicitly defined in drivers/char/seiection.c: 
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TIOCLINUX-2 

TIOCLINUX-3 

TIOCLINUX-4 

TIOCLINUX-5 

TIOCLINUX-6 

TIOCLINUX-7 

TIOCLINUX-10 


void 

void 


struct selection * 


long [8]; g * 


DUPLICATE iOCtlS 

This list does not include ioctis in the range siocdevprivate and siocprotoprivate: 


0X00000001 

0X00000002 

0X00005382 

0X00005402 

0x00005403 

0x00005404 


FDSETPRM 

FDDEFPRM 

CDROMAUDIOBUFSIZ 
SNDCTL_TMR_START 
SNDCTL_TMR_ST OP 
SNDCTL_TMR_CONTINUE 


FIBMAP 

FIGETBSZ 

SCSI_IOCTL_GET_IDLUN 

TCSETS 

TCSETSW 

TCSETSF 


Linux, 17 September 1995 


ioperm 

ioperm— Setsport input/output permissions 

SYNOPSIS 

#include <unistd.h> 

int loperm(unsigned long from, unsigned long n um.inttur n_on ); 

DESCRIPTION 

ioperm sets the port access permission bits for the process for n u m bytes starting from port address from to the value t ur n_on. 

T he use of ioperm requires root privileges. 

Only the first 0x3ff I/O ports can be specified in this manner. For more ports, the iopi function must be used. Permissions 
are not inherited on fork, but on exec they are This is useful for giving port access permissions to nonprivileged tasks 

RETURN VALUE 

On success 0 is returned. On error, -1 is returned and errno isset appropriately. 

C0NF0RMST0 

ioperm is Linux specific. 

SEE ALSO 

iopl(2) 

Linux, 21 January 1993 


iopl 

iopi—Changes I/O privilege level 
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ipc 


SYNOPSIS 

ffinclude <unistd.h> 
int iopi(int level ); 

DESCRIPTION 

iopi changes the I/O privilege level of the current process, as specified in i evei. 

Thiscall isnecessaryto allow 8514-compatible X servers to run under Linux. Because theseX servers require access to all 
655361/0 ports, the ioperm call is not sufficient. 

In addition to granting unrestricted I/O port access, running at a higher I/O privilege level also allows the process to disable 
interrupts This will probably crash the system and is not recommended. 

The I/O privilege level foranormal process is 0. 

RETURN VALUE 

0 n success 0 is returned. 0 n error, -1 is returned and err no issdt appropriately. 

ERRORS 

einval level is greater than 3. 

eperm The current user is not the superuser. 

NOTES FROM THEKERNEL SOURCE 

iopi has to be used when you want to access the I/O ports beyond the 0x3ff range: To gdt the full 65536 ports bitmapped, 
you'd need 8KB of bitmaps process, which isa bit excessive. 

SEE ALSO 

ioperm(2) 

Linux 0.99.11, 24 July 1993 


ipc 

ipc- System V IPC system calls 

SYNOPSIS 

int ipc(unsigned int call, int first, int second, 
int third, void *pt r , long fifth); 


DESCRIPTION 

ipc isa common kernel entry point for the System V IPC calls for messages, semaphores, and shared memory, call 
determines which I PC function to invoke; the other arguments are passed through to the appropriate call. 

User programs should call the appropriate functions by their usual names. 0 nly standard library implementors and kernel 
hackers need to know about ipc. 

SEE ALSO 

msgctl(2), msgget(2), msgrcv(2), msgsnd(2), semctl(2), semget(2), semop(2), shmat(2), shmctl(2), shmdt(2), shmget(2) 

Linux 1.2.4,15 April 1995 
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kill 

kin— Sends signal to a process 

SYNOPSIS 

#include <sys/types.h> 

//include <signal.h> 

DESCRIPTION 

The km system call can beused to send any signal to any process group or process. 

If pi d is positive, then signal si g is sent to pi d. In this case, 0 is returned on success and a negative value is returned on error. 

If pi d equals - 1 , then si g is sent to every process except the first one from higher numbers in the proc table to lower. In this 
case 0 is returned on success, or the error condition resulting from signaling the last process is returned. 

If pi d is less than -i,then si g is sent to every process in the process group -pi d. In this case, the number of processes the 
signal was sent to is returned and a negative value is returned for failure. 

RETURN VALUE 

0 n success, 0 is returned. 0 n error, -1 is returned and emw> isset appropriately. 

ERRORS 

EINVAL 
ESRCH 

EPERM 

BUGS 

It isimpossibleto send a signal to task number one the nitt process, for which it has not installed a signal handler. This is 
done to ensure that the system isnot brought down accidentally. 

C0NF0RMST0 

SVID, AT & T, PO SIX.1, X/O PEN , BSD 4.3 

SEE ALSO 

exit(2), exit(2), signal(2), signal(7) 

Linux, 1 N wember 1995 


An invalid signal is sent. 

T he pid or process group does not exist. N ote that an existing process might be a zombie a 
process that already committed termination, but has not yet been waitoed for. 

The effective user ID ofthe process calling kino is not equal to the effective user ID of pid, 
unless the superuser called kino. 


killpg 

knipg— Sends signal to a process group 

SYNOPSIS 

//include <signal.h> 

int killpg(int pgr p ,intsi g); 

DESCRIPTION 

kiiipg sends the signal si g to the process group pgr p . See sigaction(2) for a list of signals. If pgr p is 0, kiiipg sends the signal 
to the sending process's process group. 



link 




The sendi ng process and members of the process group must have the same effecti ve user ID, or the sender must be the 
superuser. As a single special case the continue signal sigcont may be sent to any process that is a descendant of the current 
process 

RETURN VALUE 

0 n success 0 is returned. 0 n error, -1 is returned and emno issdt appropriately. 

ERRORS 

EINVAL 
ESRCH 
ESRCH 
EPERM 

HISTORY 

Thekiiipgfunction call appeared in BSD4.0. 

SEE ALSO 

kill(2), getpgrp(2), signal(2) 

BSD Man Page 23July 1993 


sig is not a valid signal number. 

N 0 process can be found i n the process group specified by p g r p. 

The process group was given aso, but the sending process does not have a process group. 
The sending process is not the superuser and one or more of the target processes has an 
effective user ID different from that of the sending process. 


link 

link— M akesa new nameforafile 

SYNOPSIS 

#include <unistd.h> 

int link(const char *oId pat h, const char *newpat h); 


DESCRIPTION 

link creates a new link (also known as a hard link) to an existing file. 

If newpat h exists, it will not be overwritten. 

This new name may be used exactly as the old one for any operation; both names refer to the same file (and so havethesame 
permissions and ownership) and it is impossible to tell which name was the original. 


RETURN VALUE 

On success, 0 is returned. On error, -1 is returned and errno isset appropriately. 


ERRORS 

EXDEV 
EPERM 
EFAULT 
EACCES 


ENAMETOOLONG 

ENOENT 

ENOTDIR 


oidpath and newpat h arenot on thesamefilesystem. 

Thefilesystem containingoi dpath and newpat h does not support the creation of hard links 
oidpath or newpat h points outside your accessible address space 
W rite access to the directory containing newpat h is not allowed for the process's effective 
UID, or oneof the directories in oi dpat h or newpat h did not allow search (execute) 
permission. 

01 dpath or newpat h wastoo long. 

A directory component in oi dpath or newpat h does not exist or is a dangling symbolic link. 
A component used as a directory in oi dpath or newpat h isnot, in fact, a directory. 
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enomem Insufficient kernel memory was available. 

erofs Thefileison a read-only filesystem. 

eexist newpath already exists. 

emlink The file referred to by o i d p a t h already hasthe maximum number of links to it. 

eloop oidpath or newpat h containsa referenceto a circular symbolic link, that is, a symbolic link 

whose expansion containsa referenceto itself. 

enospc The device containing the file has no room for the new directory entry. 

eperm oidpath isthe. or.. entry of a directory. 

NOTES 

H ard links, as created by link, cannot span filesystems. Usesymiink if this is required. 

C0NF0RMST0 

SVID.AT&T, POSIX, BSD 4.3 

BUGS 

O n N FS file systems, the return code may be wrong i n case the N FS server performsthe link creation and dies before it can 
say so. U se stat(2) to find out if the link was created. 

SEE ALSO 

symlink(2), unlink(2), rename(2), open(2), stat(2), ln(l), link(8) 

Linux, 17 August 1994 


listen 

listen— Listens for connections on a socket 

SYNOPSIS 

#include <sys/socket.h> 
int listen(int_s,int backlog); 

DESCRIPTION 

T o accept connections, a socket isfirst created with socket(2), a willingness to accept incoming connections and a queue 
limit for incoming connections are specified with listen, and then the connections are accepted with accept(2). The listen 
call appliesonly to sockets of type sock_stream or sock_seqpacket. 

Thebtcfci'og parameter defines the maximum length the queue of pending connections may grow to. If a connection request 
arrives with the queue full, the client might receive an error with an indication of econnrefused, or, if the underlying protocol 
supports retransmission, the request may be ignored so that retries may succeed. 

RETURN VALUE 

0 n success, 0 is returned. 0 n error, -1 is returned and errno issdt appropriately. 

ERRORS 

EBADF 
ENOTSOCK 
EOPNOTSUPP 

HISTORY 

The listen function call appeared in BSD 4.2. 


The arguments is not a valid descriptor. 

The arguments is not a socket. 

T he socket is not of a type that supports the operation listen. 
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Iseek 


BUGS 

If the socket is of type afj.net and the backlog argument is greater than 128, it issilently truncated to 128. For portable 
applications, don't rely on this value since BSD (and at least some BSD -derived systems) limit the backlog to 5. 

SEE ALSO 

accept(2), connect(2), socket(2) 

BSD Man Paget 23July 1993 


llseek 

_iiseek— Repositionsthe read/write file offset 

SYNOPSIS 

ffinclude <unistd.h> 
ffinclude <linux/unistd.h> 

_syscall5(int, llseek, uint, fd, ulong, hi, ulong, lo, loff_t*,res,uint,wh); 

int llseek(unsigned int fd, unsigned long offsethigh, 

unsigned long offset_l ow,loff_t * result , unsigned int whence); 

DESCRIPTION 

The_iiseek function repositions the offset of thefile descriptor fd to (of f set. hi gh«32) | offset_iow bytes relative to the 
beginning of the file the current position in thefile, or the end of thefile, depending on whether whence issEEK_SET, 
SEEK_cuR,or seek_end, respectively. It returns the resulting file position in the argument result. 

RETURN VALUES 

Upon successful completion, _iiseek returns®. Otherwise, a value of -i is returned and errno is set to indicate the error. 

ERRORS 

ebadf f d is not an open file descriptor. 

einval (tie is invalid. 

C0NF0RMST0 

Thisfunction is Linux specific. 

BUGS 

T here is no support for files with a size of 2G B or more. 

SEE ALSO 

lseek(2) 

Linux 1.2.9,10 Junel995 


Iseek 

iseek- Repositions read/write file offset 

SYNOPSIS 

ffinclude <unistd.h> 

off_t lseekfint fi Ides,off _t offset 


it ,int whence); 
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DESCRIPTION 

T he lseek function repositionsthe offset of thefile descriptor f i i des to the argument off set according to the directive 
whence . T he argument f i i des must be an open file descriptor, lseek repositions the fi le poi nter f i i des as follows 
If whence issEEK_SET, the offset i s set to offset bytes 
If whence issEEK_cuR, the offset isset to itscurrent location plusoffset bytes. 

If whence issEEK_END, theoffsdt issdt to thesizeof thefile plusof f set bytes. 

The lseek function allows the file offset to beset beyond the end of the existing end-of-file of the file If data is later written 
at this point, subsequent reads of the data in the gap return bytes of zeros (until data is actually written into the gap). 
Somedevicesareincapableof seeking. The value of the pointer associated with such a device is undefined. 

RETURN VALUES 

Upon successful completion, lseek returns the resulting offset location as measured in bytes from the beginning of thefile. 
Otherwise, a value of-i is returned and errno is set to indicate the error. 

ERRORS 

ebadf fi i des isnotan open file descriptor. 

espipe fiides is associated with a pipe socket, or FIFO. 

einval whence is not a proper value 

C0NF0RMST0 

POSIX, BSD 4.3 

BUGS 

This document's use of whence is incorrect English, but maintained for historical reasons. 

SEE ALSO 

dup(2), open(2), fseek(3) 

Linux 1.2.9,10 Junel995 


mkdir 

mkdii— C reates a di rectory 

SYNOPSIS 

//include <sys/types.h> 

//include <fcntl.h> 

//include <unistd.h> 

int mkdir(const char ‘pathname, mode_t mode); 

DESCRIPTION 

mkdir attempts to create a di rectory named p a t h n a me. 

mode specifies the permissions to use. It is modified by the process's umask in the usual way: the permissionsof the created 
file is (mode & "umask). 

The newly created directory will be owned by the effective UID of the process If the directory containing thefile has the set 
group ID bit set, or if the filesystem is mounted with BSD group semantics, the new directory will inherit the group 
ownership from its parent; otherwise it will be owned by the effective GID of the process. 

If the parent directory has the set group ID bit set, so will the newly created directory. 



mknod 
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RETURN VALUE 

mkdir returns oon success, or -i if an error occurred (in which case, errno is set appropriately). 

ERRORS 

EEXIST 
EFAULT 
EACCES 

ENAMETOOLONG 
ENOENT 
ENOTDIR 
ENOMEM 
EROFS 
ELOOP 

ENOSPC 
ENOSPC 

BUGS 

In some older versionsof Linux (for example, 0.99pl7) all the normal filesystems sometime allow the creation of two filesin 
the same directory with the same name. This occurs only rarely and only on a heavily loaded system. It is believed that this 
bug was fixed in the M inix filesystem in Linux 0.99pl8 prerelease: and it is hoped that it was fixed in the other filesystems 
shortly afterward. 

T here are many infelicities in the protocol underlying NFS. 

SEE ALSO 

read(2), write{2), fcntl(2), close(2), unlink(2), open(2), mknod(2), stat(2), umask(2), mount(2), socket(2), socket(2), fopen(3) 

Linux 1.0, 29 March 1994 


p a t h n a me already exists (not necessarily as a directory), 
pat hname points outside your accessi ble address space. 

The parent di rectory does not allow write permission to the process, or one of the 
directories in pat hname did not allow search (execute) permission, 
pathname WaStOO long. 

A directory component in pat hname does not exist or is a dangling symbolic link. 

A component used as a directory in pathname is not, in fact, a directory. 

I nsufficient kernel memory was available. 

p a t h n a me refers to a file on a read-only filesystem and write access was requested, 
pat hname contains a reference to a circular symbolic link, that is, a symbolic link whose 
expansion contains a reference to itself. 

Thedevice containing pathnamehas no room for the new directory. 

The new directory cannot be created because the user's disk quota is exhausted. 


mknod 

mknod— C reatesa directory 

SYNOPSIS 

#include <sys/types.h> 

//include <sys/stat.h> 

//include <fcntl.h> 

//include <unistd.h> 

int mknod(const char ‘pathname, mode_t mode,dev_t dev); 

DESCRIPTION 

mknod attempts to create a filesystem node (file, device special file, or named pipe) named pat hname, specified by mode and dev. 
mo d e specifies both the permissions to use and the type of node to be created. 

It should be a combination (using bitwise or) of one of the file types listed below and the permissionsfor the new node. 

The permissions are modified by the process's umask in the usual way: The permissions of the created node is (mode & 

"umask). 
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Thefile type should be one of s_ifreg, s_ifchr, s_ifblk, or s_ififo to specify a normal file (which will be created empty), 
character special file, block special file, or FIFO (named pipe), respectively, or 0, which will create a normal file. 

If thefiletype iss_iFCHR or s_ifblk, then dev specifies the major and minor numbers of the newly created device special file; 
otherwise it is ignored. 

The newly created node will be owned by the effective UID of the process If the directory containing the node has the sdt 
group ID bit set, or if the filesystem is mounted with BSD group semantics, the new node will inherit the group ownership 
from its parent directory; otherwise it will be owned by the effective GID of the process. 

RETURN VALUE 

mknod returns oon success or -i if an error occurred (in which case, errno is set appropriately). 

ERRORS 

EPERM 

EINVAL 
EEXIST 
EFAULT 
EACCES 

ENAMETOOLONG 
ENOENT 
ENOTDIR 
ENOMEM 
EROFS 
ELOOP 

ENOSPC 

BUGS 

In some older versions of Linux (for example, 0.99pl7) all the normal filesystems sometime allow the creation of two files in 
the same directory with the same name. This occurs only rarely and only on a heavily loaded system. It is believed that this 
bug was fixed in the M inix filesystem in Linux 0.99pl8 prerelease; and it is hoped that it was fixed in the other filesystems 
shortly afterward. 

mknod cannot be used to create directories or socket files, and cannot be used to create normal files by users other than the 
superuser. 

There are many infelicities in the protocol underlying N FS. 

SEE ALSO 

read(2), write(2), fcntl(2), close(2), unlink(2), open(2), mkdir(2), stat(2), umask(2), mount(2), socket(2), fopen(3) 

Linux 1.0, 29 March 1994 


mode requested creation of something other than a FIFO (named pipe), and thecaller is not 
thesuperuser; also returned if the filesystem containing pathname doesnot support the type 
of node requested. 

mode requested creation of something other than a normal file device special file or FIFO. 
pathname already exists 

pat hname points outside your accessi ble address space. 

The parent di rectory does not allow write permission to the process or one of the 
directories in pat hname did not allow search (execute) permission, 
pathname WaStOO long. 

A directory component in pat hname doesnot exist or is a dangling symbolic link. 

A component used as a directory in pathname is not, in fact, a directory. 

I nsufficient kernel memory was available. 

p a t h n a me refers to a fi le on a read-only filesystem and write access was requested, 
pat hname contains a reference to a circular symbolic link, that is a symbolic link whose 
expansion contains a reference to itself. 

The device contai ning p a t h n a me has no room for the new node 


mlock 

miock— D isables paging for some parts of memory 



mlockall 




SYNOPSIS 

#include <sys/mman.h> 

int mlock(const void ‘addr, size_t len); 

DESCRIPTION 

miock disables paging for the memory in the range starting at add r with length i en bytes. All pages that contain apart of the 
specified memory range are guaranteed to be resident in RAM when themiock system call returns successfully and they are 
guaranteed to stay in RAM until the pages are unlocked again by muniock or muniockaii or until the process terminates or 
starts another program with exec. Child processes do not inherit page locks acrossa fork. 

M emory locking has two main applications real-time algorithmsand high-security data processing. Real-timeapplications 
require deterministic timing, and, like scheduling, paging is one major cause of unexpected program execution delays Real¬ 
time applications will usually also switch to a real-time scheduler with sched setscheduier. 

C ryptographic security software often handles critical bytes such as passwords or secret keys as data structures. As a result of 
paging, these secrdts could be transferred onto a persistent swap store medium, where they might be accessible to the enemy 
long after the security software has erased the secrdts in RAM and terminated. 

M emory locks do not stack, that is, pages that have been locked several times by calls to miock or miockaii will be unlocked 
by a single call to muniock for the corresponding range or by muniockaii. Pages that are mapped to several locationsorby 
several processes stay locked into RAM as long as they are locked at least at one location or by at least one process 
On POSIX systems on which miock and muniock are available _posix_memlock_range isdefined in <unistd.h> and the value 
pagesize from <iimits.h> indicates the number of bytes per page. 

RETURN VALUE 

0 n success miock returns 0 .0 n error, -i is returned, errno is set appropriately, and no changes are made to any locks in the 
address space of the process 

ERRORS 

ENOMEM 

EPERM 

EINVAL 

STANDARDS 

POSIX.lb, SVR4 

SEE ALSO 

munlock(2), mlockall(2), munlockall(2). 

Linux 1.3.43, 26 November 1995 


Some of the specified address range does not correspond to mapped pagesin the address 
space of the process or the process tried to exceed the maximum number of allowed locked 
pages 

The calling process does not have appropriate privileges. 0 nly root processes are allowed to 
lock pages. 

ten was not a positive number. 


mlockall 

miockaii— D isables paging for calling process 

SYNOPSIS 

#include <sys/mman,h> 
int mlockall(int flags); 
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DESCRIPTION 

miockaii disables paging for all pages mapped into the address space of the calling process. This includes the pages of the 
code, data and stack segments, shared libraries, user space kernel data, shared memory, and memory-mapped files All 
mapped pages are guaranteed to be resident in RAM when themiockaii system call returns successfully and they are 
guaranteed to stay in RAM until the pages are unlocked again by muniock or muniockaii or until the process terminates or 
starts another program with exec. C hild processes do not inherit page locks across a fork. 

M emory locking has two main applications real-time algorithmsand high-security data processing. Real-ti me appl ications 
require deterministic timing, and, like scheduling, paging is one major cause of unexpected program execution delays Real- 
ti me applications will usually also switch to a real-time scheduler with sched setscheduier. Cryptographic security software 
often handles critical bytes such as passwords or secret keys as data structures. As a result of paging, these secrets could be 
transferred onto a persistent swap store medium, where they might be accessible to the enemy long after the security software 
has erased the secrets in RAM and terminated. For security applications, only small partsof memory have to be locked, for 
which miock is available. 

T he f i a g s parameter can be constructed from the logical or of the following constants 

mcl_current Lock all pages that are currently mapped into the address space of the process. 

mcl_future Lock all pagesthatwill becomemapped into the address space of the process in thefuture. 

These could be for instance, new pages required by agrowing heap and stack as well as new 
memory mapped files or shared memory regions. 

If mcl_future has been specified and the number of locked pages exceeds the upper limit of allowed locked pages the system 
call that caused the new mapping will fai I with enomem. If these new pages have been mapped by the growing stack, the kernel 
will deny stack expansion and send a sigsegv. 

Real-time processes should reserve enough locked stack pages before entering the time-critical section, so no page fault can be 
caused by function calls This can be achieved by calling a function that has a sufficiently large automatic variable and that 
writes to the memory occupied by this large array in order to touch these stack pages This way, enough pages will be 
mapped for the stack and can be locked into RAM . The dummy writes ensure that not even copy-on-write page faults can 
occur in the critical section. 

M emory locks do not stack, that is pages that have been locked several times by calls to miockaii or miock will be unlocked 
by a single call to muniockaii. Pages that are mapped to several locationsor by several processes stay locked into RAM as long 
as they are locked at least at one location or by at least one process. 

On POSIX systems on which miockaii and muniockaii are available, posix memlock isdefined in <unistd.h>. 

RETURN VALUE 

On success miockaii returns 0 . On error, -i is returned and errno is set appropriately. 

ERRORS 

ENOMEM 
EPERM 

EINVAL 

STANDARDS 

POSIX.lb, SVR4 

SEE ALSO 

munlockall(2), mlock(2), munlock(2) 


The process tried to exceed the maximum number of allowed locked pages. 

The calling process does not have appropriate privileges. 0 nly root processes are allowed to 
lock pages. 

U nknown flags were specified. 


Linux 1.3.43, 26 November 1995 
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mmap,munmap 

mmap, munmap— M ap or unmap files or devices into memory 

SYNOPSIS 

#include <unistd.h> 

#include <sys/mman.h> 

#ifdef POSIX MAPPED FILES 

void * mmap(void *s t a r t , size_t Iength,int prot ,int flags,int f d,off_t offset ); 
int munmap(void ‘start, size_t Iength); 

#endif 


DESCRIPTION 

Themmap function asksto map i ength bytes starting at offset off set from thefile (or other object) specified by f d into 
memory, preferably at address start. This latter address is a hint only, and is usually specified as®. The actual place where 
the object is mapped is returned by mmap.Theprot argument describes the desired memory protection. It has the following 
bits 

prot_exec P ages may be executed. 

prot_read Pagesmay be read. 

protjvrite P ages may be written. 

T he f i a g s parameter specifies the type of the mapped object, mapping options, and whether modifications made to the 
mapped copy of the page are private to the processor are to be shared with other references. It has the following bits 
map_fixed Do not select a different address than the one specified. If the specified address cannot be 

used, mmap will fail. If map_fixed is specified, start must be a multiple of the pagesize Use of 
thisoption is discouraged. 

map_shared Share this mapping with all other processesthat map this object. 

map_private Create a private copy-on-write mapping. 

These three flags are described in POSIX.4. Linux also knows about map_denywrite, map_executable, and map_anon<ymous). 
The munmap system call deletes the mappings for the specified address range and causes further references to addresses within 
the range to generate in valid memory references. 

RETURN VALUE 

0 n success, mmap returns a pointer to the mapped area. 0 n error, map_failed (-i ) is returned and errno is set appropriately. 
On success, munmap returns®, and on failure it returns-i and sets errno (probably to einval). 


ERRORS 

EBADF 

EACCES 

EINVAL 

ETXTBUSY 

EAGAIN 

ENOMEM 


f d is not a valid file descriptor (and map_anonymous was not set). 

map_private was asked, but f d is not open for reading. 0 r map_shared was asked and 

protjvrite isset, f d is not open for writing. 

start ori ength, and offset aretoo large, or not aligned on bpagesize boundary. 
map_denywrite was set but the object specified by f d isopen for writing. 

Thefile has been locked, or too much memory has been locked. 

No memory is available 


C0NF0RMST0 

POSIX.4. 
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SEE ALSO 

getpagesize(2), nsync(2), S h m _open(2), B. 0. Gallmeister, POSIX.4 ,0 'Reilly, pp. 128-129,389-391. 

Linux 1.3.86,12 April 1996 


modify_ldt 

modif y_idt— G ets or sets ldt 

SYNOPSIS 

ffinclude <linux/ldt.h> #include <linux/unistd.h> 

_syscall3( int, modify_ldt, int, func, void *, ptr, unsigned long, bytecount ) 
int modify_ldt(int func, void *ptr, unsigned long bytecount); 

DESCRIPTION 

modify_idt readsor writes the local descriptor table (idt) for a process T he idt is a per-process memory-management table 
used by the i386 processor. For more information on thistable, see an Intel 386 processor handbook. 

Whent unc iso, modify_idt reads the ldt into the memory pointed to by ptr .The number of bytes read is the smaller of 
bytecount and the actual size of theidt. 

W hen func is i, modify_idt modifies one ldt entry, ptr points to a modi f y.i dt j dt.s structure and bytecount must equal the 
size of this structure 

RETURN VALUE 

0 n success modify_idt returns either the actual number of bytes read (for reading) or o (for writing). 0 n failure, modify_idt 
returns -i and sets errno. 

ERRORS 

enosys func is neither o nor t, 

einval ptr iso.ortunc is i and bytecount is not equal to the size of the structure 

modi fy.i dt.i dt.s, or func isi and the new idt entry has illegal values. 
efault ptr points outside the address space. 

SEE ALSO 

vm86(2) 

Linux 1.3.6, 22July 1995 

get_kernel_syms,createjnodule, init jiodule, delete_module 

get_kernel_syms, create_module, initjnodule, delete_module— Loadable module Support 

SYNOPSIS 

ffinclude <linux/module.h> 

int get_kernel_syms(struct kernel_sym ‘table); 


int createjnodule(char *module_name, unsigned long 





get_kernd_9/m$ create_moduld init_module ddete_module 
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int init_module(char *module_name, char ‘code, unsigned codesize, 
struct mod_routines ‘routines, struct symbol_table ‘symtab); 

int delete_module(char *module_name); 

struct kernel_sym { 

unsigned long value; 
char name[SYM_MAX_NAME]; 


struct mod_routines { 
int (*init)(void); 
void (‘cleanup)(void); 


struct module_ref { 

struct module ‘module; 
struct module_ref ‘next; 


struct symbol_table { 

int size; /* total, including string table!!! */ 
int n_symbols; 

struct internal_symbol symbol[0]; 
struct module_ref ref[0]; 


DESCRIPTION 

These system calls have not yet been included in any library, which means that they have to be called by the 
syscaii(_NR_f unction) mechanism. get_kernei_syms(table); hastwo uses: First, if table isNULL, this call will only return the 
number of symbols, including module names, that are available This number should be used to reserve memory for that 
many items of struct kernel sym. 

If table is not null, this call will copy all kernel symbols and module names (and version info) from the kernel to the space 
pointed to by table. The entries are ordered in moduleLlFO order. For each module an entry that describes the module will 
be followed by entries describing thesymbols exported by this module. 

N ote that for symbols that describe a module, the value part of the structure will contain the kernel address of the structure 
that describes the module 

The name part of the structure is the module name prepended with #, as in #my module. The symbol that describes a module 
will appear before the symbols defined by this module 

Ahead of the kernel resident symbols, a module name symbol with the "dummy" name# will appear. This information can 
be used to build a table of module references when modules are stacked (or layered). create_moduie(moduie_name, size); will 
allocate size bytes of kernel space for a module and also create the necessary kernel structures- called name- for the new 
module The module will now exist in kernel space with thestatusMODjjNiNuiALizED.init module(moduie_name, code, 
codesize, routines, symtab);. 

This is the actual "module loader" that will load the module named name into the kernel. The parameters code and codesize 
refer to the relocated binary object module that is codesize bytes long. Note that the first 4 bytes will be used as a reference 
counter in kernel space, updated by the mod_inc_use_count and mod_dec_use_count macros. 
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Thefunctionsdescribed in routines will be used to start and stop the module. These pointers should thereforecontain the 
addressesof theinit_moduieo and cieanupjnoduieo functionsthathaveto be defined for all loadable modules. 

If a module wants to export symbols for use by othe modules, or if the module makes refeences to symbols defined by othe 
modules, theparamete symtab has to point to a structure that describes these. A null value for symtab meansthat no symbols 
are exported and no refeences to othe modules are made. 

The symtab that will be copied intothekenel consists of a symbol table structure immediately followed by a string table, 
containing thenames of the symbols defined by the module The size element hasto include thesize of thisstring table as 
well. Speial consideationsfollow. 

The n_symbois and n_refs elements tells how many symbols and how many module references are included in the symbol 
table structure. Immediately after these integers, the array of symbol definitionsfollows The name element in each struct 
internal symbol should actually not be an ordinary pointer, but instead the offset of the corresponding string table entry 
relative to the start of the symbol table structure. 

When all defined symbols have been listed, the symboi_tabie structure continues with thearray of module references, as 
described by the struct moduie_ref elements Only the module field of these structures have to be initialized. The module 
addresses that were obtained from a previous get_kernei_syms call, for elements with names starting with # should be copied 
to thisfidd. 

If the module could be successfully loaded, and if the call to the module function initjnoduieo also succeeds, the status of 
the module will be changed to mod_running. Otherwise, the kernel memory occupied by module will be freed, 
deietejnoduie (moduie_name ); should beused to unload a module. If the module reference count shows that the module is not 
active and if there are no references to this module from other modules, the module function cieanupjnoduieo will be 
called. If all these steps succeed, the kernel memory occupied by the module and its structures will be freed. 

DIAGNOSTICS 

If there are any errors, these functions will return the value -i, and the global variable errno will contain the error number. A 
descriptive text will also be written on the console device. 

SEE ALSO 

insmod(l), rmmod(l), lsmod(l), ksyms(l) 

HISTORY 

The module support was first conceived by Anonymous 

Linux version by BasLaarhoven (bas@vimec.m), 0.99.14 version by Jon Tombs (jon@gtex 02 .us.es), extended by Bjorn 
Ekwall (bj0rn@blox.se). 

BUGS 

Naah... 

Linux, 25January 1995 


mount,umount 

mount, umount— M ount and unmount filesystems. 


SYNOPSIS 

#include <sys/mount.h> 

(/include <linux/fs.h> 

int mount(const char *speci al f i I e , const char * di r , 

const char * f i I esystemtype , unsigned long r wf I a g , const void * data); 
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DESCRIPTION 

mount attaches the filesystem specified by sped ai f i i e (which is often a device name) to the directory specified by di r. 
umount removes the attachment of thefilesystem specified byspeci ai f i i e or di r. 

0 nly the superuser may mount and unmount filesystems. 

Thef i I esystemtypc argument may take one of the values listed in /proc/filesystems (such asminix, ext 2 , msdos, proc, nfs, 
iso9660). 

Thenvf i ag argument has the magic number oxcoed in the top 16 bits, and various mount flags (as defined in <iinux/fs.h>) in 
the low order 16 bits: 

#define MS_RDONLY 1 /* mount read-only */ 

#define MS_NOSUID 2 /* ignore suid and sgid bits */ 

#define MS_NODEV 4 /* disallow access to device special files */ 

#define MS_N0EXEC 8 /* disallow program execution */ 

#define MS_SYNC 16 /* writes are synced at once */ 

#define MS_REMOUNT 32 /* alter flags of a mounted FS */ 

#define MSJIGC_VAL 0XC0ED0000 

If the magic number is absent, then the last two arguments are not used. 

The dat a argument is interpreted by the different filesystems. 

RETURN VALUE 

0 n success, 0 is returned. 0 n error, -1 is returned and errno issdt appropriately. 


ERRORS 


Thefollowing error values result from filesystem type independent errors. Each filesystem type may have itsown special 
errors and itsown special behavior. See the kernel source code for details 


EPERM 

ENODEV 

ENOTBLK 

EBUSY 


EINVAL 


EFAULT 

ENOMEM 

ENAMETOOLONG 

ENOENT 

ENOTDIR 

EACCES 


ENXIO 

EMFILE 


The user is not the superuser. 

fi 1 e s y s t e mt y p e not configured in the kernel. 

sped ai f i 1 e is not a block device (if a device was required). 

speci ai fi 1 e is already mounted. 0 r it cannot be remounted read-only because it still holds 
files open for writing. 0 r, it cannot be mounted on di r because di r is still busy (it is the 
working directory of some task, the mount point of another device, has open files and so 
on). 

speci a 1 f i 1 e had an invalid superblock. Or, a remount was attempted, while sped a 1 f i 1 e 
was not already mounted on di r. 0 r, an umount was attempted, while di r was not a mount 
point. 

0 ne of the pointer arguments points outside the user address space 
T he kernel could not allocate a free page to copy filenames or data into. 

A pathname was longer than maxpathlen. 

A pathnamewasempty or had a nonexistent component. 

Thesecond argument, oraprefixof the first argument, is not a directory. 

A component of a path was not searchable 

0 r, mounting a read-only filesystem was attempted without giving theMS_RDONLY flag. 

0 r, the block devices pec i ai f i 1 e islocated on a filesystem mounted with the ms_nodev 
option. 

Themajor number of the block devices peci ai fii e is out of range 
(I n case no block device is required:) T able of dummy devices isfull. 
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C0NF0RMST0 

These functions are rather Linux specific. 

SEE ALSO 

mount(8), umount(8) 

Linux 1.1.67, 28 November 1994 


mprotect 

mprotect— Controls allowable accesses to a region of memory 

SYNOPSIS 

#include <sys/mman.h> 

int mprotect(caddr_t ad dr, size_t *1e n, int prot); 

DESCRIPTION 

mprotect controls how a section of memory can be accessed. If an access is disallowed by the protection given it, the program 
receives a sigsegv. 

prot is a bitwise-0 R of the following values: 
prot_none The memory cannot be accessed at all. 

prot_read T he memory can be read. 

prot_write Thememory can bewritten to. 

prot_exec T he memory can contain executing code. 

The new protection replaces any existing protection. For example, if the memory had previously been marked prot_read, and 
mprotect isthen called with prot prot_write, it will no longer be readable 

RETURN VALUE 

On success, mprotect returns 0 . On error, -i is returned and errno is set appropriately. 

ERRORS 

EINVAL 
EFAULT 
EACCES 

ENOMEM 

EXAMPLE 

#include <stdio.h> 

#include <stdlib.h> 

#include <errno.h> 

#include <sys/mman.h> 

int 


addr is not a valid pointer. 

T he memory cannot be accessed. 

The memory cannot be given the specified access This can happen, for example if you 
mmap(2) a file to which you have read-only access, then ask mprotect to mark it prot_write. 
Internal kernel structures could not be allocated. 
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/* Allocate a buffer; it will have the default 
protection of PR0T_READ|PROT_WRITE. */ 
p = malloc(1024); 
if HP) { 

perror("Couldn't malloc(1024)"); 
exit(errno); 


/* Mark the buffer read-only. */ 
if (mprotect(p, 1024, PR0T_READ)) { 
perror("Couldn 1 t mprotect"); 


c = p[666]; /* Read; ok */ 

p[666] = 42; /* Write; program dies on SIGSEGV */ 

exit(0); 


SEE ALSO 

mmap(2) 


Linux 1.2, 23 Junel995 


mremap 

mremap— Remaps a virtual memory address 

SYNOPSIS 

#include <unistd.h> 

#include <sys/mman.h> 

void * mremap(void * old_address , size_t oId_ siz e , size_t new_s i ze , unsigned long flags) 

DESCRIPTION 

mremap expands (or shrinks) an existing memory mapping, potentially moving it at the same time (controlled by thef lags 
argument and the avail able virtual address space). 

oi d_addr ess is the old address of the virtual memory block that you want to expand (or shrink). Note that oi d_ address has to 
be page aligned, oi d_ s i ze istheold size of the virtual memory block, new.si ze is the requested size of the virtual memory 
block after the resize 
T he f i a g s argument is a bitmap of flags 

In Linux the memory is divided into pages. A user process has one or linear virtual memory segments Each virtual memory 
segment has one or more mappings to real memory pages (in the page table). Each virtual memory segment hasitsown 
protection (access rights), which may cause a segmentation violation if the memory is accessed incorrectly (for example, 
writing to a read-only segment). Accessing virtual memory outside of the segments will also cause a segmentation violation, 
mremap usesthe Linux page table scheme mremap changes the mapping between virtual addresses and memory pages Thiscan 
be used to implement a very efficient reaiioc. 
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FLAGS 

mremap_maymove I ndicates whether the operation should fail, or changes the virtual address if the resize 

cannot be done at the current virtual address. 

RETURN VALUE 

On success, mremap returnsa pointer to the new virtual memory area. 0 n error, -i is returned, and errno isset appropriately. 

ERRORS 

EINVAL 
EFAULT 


EAGAIN 
ENOMEM 

SEE ALSO 

getpagesize(2), reaiioc(3), maiioc(3), brk(2), sbrk(2), mmap(2), your favorite 0 S text book for more information on paged 
memory. (M odern 0 perating Systemsby Andrew S. T annenbaum, InsideLinux by Randolf Bentson, The Design of the UN IX 
OperatingSystav by M auricej. Bach.) 

Linux 1.3.87,12 April 1996 


An invalid argument was given. M ost likely oi d. add r es s was not page aligned. 

Segmentation fault. Someaddressin the range o i d_ address tool d.address+oi d.size isan 
invalid virtual memory addressfor this process. You can also gdt efault even if there exist 
mappi ngs that cover the whole address space requested, but those mappings are of different 
types. 

The memory segment is locked and cannot be remapped. 

The memory area cannot be expanded at the current virtual address, and the mremap_may move 
flag is not set in f i ags. 0 r there is not enough (virtual) memory available. 


msgctl 

msgcti— H andles message control operations 

SYNOPSIS 

# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/msg.h> 

int cmd, struct msqid_ds *buf; 


DESCRIPTION 

Thefunction performs the control operation specified bycmd on the message queue with identifier ms qi d . Legal values for cmd 

are 

ipc_stat Copies info from the message queue data structure into the structure pointed to by buf . The 

user must have read access privileges on the message queue. 

ipc_set W rites the values of some members of the msqid ds structure pointed to by buf to the 

message queue data structure, updating also itsmsg_ctime member. Considered members 
from the user-supplied struct msqid ds pointed to by buf aremsg_perm.uid, msg_perm.gid, 
and msg_perm.mode /* only lowest 9-bits */ msg_qbytes. 

The calling process effective user ID must be one among superuser, creator or owner of the 
message queue Only the superuser can raise the msg_qbytes value beyond the system 
parameter msgmnb. 

ipc_rmid Remove immediately the message queue and its data structures awakeni ng all waiting reader 

and writer processes (with an error return and errno sdt to eidrm). The calling process 
effective user ID must be one among superuser, creator or owner of the message queue. 
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RETURN VALUE 

If successful, the return value will be otherwise the return value will be -i with errno indicating the error. 

ERRORS 

For a failing return, errno will be set to one of the following values: 

eaccess T he argument cmd is equal to ipc_stat, but the calling process has no read access permis¬ 

sions on the message queue ms q i d. 

efault The argument cmd hasvalueiPC_SEToriPC_STAT,buttheaddresspointedtobybuf isn't 

accessible 

eidrm The message queue was removed. 

einval Invalid value for cmd or msqi d. 

eperm The argument cmd hasvalueiPC_SEToriPC_RMiD, but the calling process effective user ID 

has insufficient privileges to execute the command. N ote that this is also the case of a 
nonsuperuser process trying to increase the msg_qbytes value beyond the value specified by 
the system parameter msgmnb. 

NOTES 

TheiPC_iNFO, msg_stat, and msg_info control calls are used by the ipcs(l) program to provide information on allocated 

resources In the future these can be modified as needed or moved to a proc file system interface 

SEE ALSO 

ipc(5), msgget(2), msgsnd(2), msgrcv(2) 

Linux 0.99.13,1 November 1993 


msgget 

msgget— Getsa message queue identifier 

SYNOPSIS 

# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/msg.h> 

int msgget ( key_t key, int msgf I g ); 

DESCRIPTION 

The function returns the message queue identifier associated to the value of the key argument. A new message queue is 
created if key has value ipc_private or key isn't ipc_private, no existing message queue is associated to key, and ipc_creat is 
asserted in ms gf i g (that is, msgf i g &ipc_creat isn't 0 ). The presence in msgf 1 g of the fields ipc_creat and ipc_excl plays the 
same role with respect to the existence of the message queue, as the presence of o_creat ando_ExcL in the mode argument of 
the op_en(2) system call: That is, the msgget function fails if ms gf 1 g asserts both ipc_creat and ipc_excl and a message queue 
already exists for key. 

Upon creation, the lower 9 bits of the argument msgf 1 g define the access permissions (for owner, group, and others) to the 
message queue in the same format, and with thesame meaning, as for the access permissions parameter in theopen(2) or 
creat(2) system calls (though the execute permissions are not used by the system). 

Furthermore while creating, the system call initializes the system message queue data structure msqid ds asfollows 
msg_perm.cuid and msg_perm.uid are set to the effective user ID of the calling process 
msg_perm.cgid and msg_perm.gid are set to the effective group ID of the calling process 
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The lowest-order 9 bits of msg_perm. mode are set to the lowest-order 9 bit of msgf i g. 
msg_qnum, msg_lspid, msg_lrpid, msg_stime, and msg_ntime are Set to 0. 
msg_ctime isset to the current ti me 
msg_qbytes is set to the system limit MSGMNB. 

If the message queue already exists, the access permissions are verified, and a check is made to see whether it is marked for 
destruction. 

RETURN VALUE 

If successful, the return value will be the message queue identifier (a positive integer), otherwise-i with errno indicating the 
error. 

ERRORS 

For a failing return, errno will be set to one of the following values: 

eacces A message queue exists for key , but the calling process has no access permissions to the 

queue 

eexist A message queue exists for key and msgf i g was asserting both ipc_creat and ipc_excl. 

eidrm Themessagequeueismarked asto beremoved. 

enoent No message queue existsfor key and msgf i g wasn't asserting ipc_creat. 

enomem A message queue has to becreated butthesystem hasnot enough memory for the new data 

structure. 

enospc A message queue has to becreated butthesystem limit for the maximum number of 

message queues (msgmni) would be exceeded. 

NOTES 

ipc_private isn't a flag field, butakey_t type. If this special value is used for key, the system call ignores everything but the 
lowest-order 9 bits of msgf i g and creates a new message queue (on success). 

Thefollowingisasystem limit on message queue resources affecting a msgget call: 

msgmni Systemwide maximum number of message queues; policy dependent. 

BUGS 

Use of ipc_private doesn't inhibit other processes the access to the allocated message queue. 

As for the files, there is currently no intrinsic way for a process to ensure exclusive access to a message queue. Asserting both 
ipc_creat and ipc_excl in msgf i g only ensures (on success) that anew message queue will becreated; it doesn't imply 
exclusive access to the message queue. 

SEE ALSO 

ftok(3), ipc(5), msgctl(2), msgsnd(2), msgrcv(2) 

Linux 0.99.13,1 November 1993 


msgop 

msgop— C ompletes message operations 

SYNOPSIS 

# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/msg.h> 
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int msgsnd ( int ms q i d, struct msgbuf *msgp",int msgsz,int msgflg ); 

int msgrcv ( int ms q i d, struct msgbuf *msgp,int msgsz.long ms gt y p,int msgflg ); 

DESCRIPTION 

To send or receive a message, the calling process allocates a structure that looks like thefollowing: 

struct msgbuf { 

long mtype; /* message type, must be > 0 */ 
char mtext[1]; /* message data */ 

but with an array mtext of size msgsz,anonnegativeintegervalue.The structure member mtype must have a strictly positive 
integer value that can be used by the receiving processfor message selection (see the section about msgrcv). 

The calling process must have write access permissions to send and read access permissionsto receive a message on the queue. 
T he msgsnd system call queues a copy of the message pointed to by the ms g p argument on the message queue whose identifier 
is specified by the value of the ms qi d argument. 

The argument ms gf i g specifies the system call behavior if queuing the new message will require more than msg_qbytes in the 
queue Asserting ipc_nowait, the message will not be sent and the system call fails, returning with errno set to eagain. 
Otherwise the process is suspended until the condition for the suspension no longer exists (in which case the message is sent 
and the system call succeeds), orthe queue isremoved (in which case the system call fails with errno set to eidrm), or the 
process receives a signal that has to be caught (in which case the system call fails with errno set to eintr). 

Upon successful completion, the message queue data structure is updated asfollows: 
msg_ispid Set to the process D of the calling process 

msg_qnum Incremented by 1. 

msg_stime Set to the current time. 

The system call msgrcv reads a message from the message queue specified by ms q i d into the msgbuf pointed to by the ms gp 
argument, removing from the queue on success, the read message. 

The argument ms gsz specifies the maxi mum size in bytes for the member mtext of the structure pointed to by the ms gp 
argument. If the message text has length greater than ms gsz, then if themsgf i g argument asserts msg_noerror, the message text 
will be truncated (and the truncated part will be lost); otherwise, the message isn't removed from the queue and thesystem 
call fails, returning with errno set to e 2 big. 

The argument ms gtyp specifies the type of message requested asfollows: 

If ms g t y p is 0 , the message on the queue's front is read. 

If msgtyp isgreater than 0, the first message on the queue of type msgtyp isread if msg_except isn't asserted by the ms g f 1 g 
argument; otherwise the first message on the queue of type not equal to msgtyp will be read. 

If msgtyp is less than 0 , the first message on the queue with the lowest type less than or equal to the absolute value of ms gtyp 
will be read. 

Themsgf 1 g argument asserts none, one, or more (OR-ing them) among the following flags: 

ipc_nowait For immediate return if no message of the requested typeison thequeue. Thesystem call 

fails with errno set to ENOMSG. 

msg_except Used with msgtyp greater than 0 to read the first message on the queue with message type 

that differs from msgtyp. 

msg_noerror T o truncate the message text if longer than ms g s z bytes. 
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If no message of the requested type is available and ipc_nowait isn't asserted in ms gf i g , the calling process is blocked until one 
of thefollowing conditions occurs: 

A message of the desi red type is placed on the queue 

The message queue is removed from the system. In such a case the system call fails with ermo set to eidrm. 

The calling process receives a signal that has to be caught. In such a case the system call fails with ermo set to eintr. 

Upon successful completion, the message queue data structure is updated asfollows: 
msg_irpid Set to the process D of the calling process 

msg_qnum D ecremented by 1. 

msg_rtime Set to the current time. 

RETURN VALUE 

On a failure, both functions return -i with ermo indicating the error; otherwise, msgsnd returns 0 and msgrvc returns the 
number of bytes actually copied into themtext array. 

ERRORS 

W hen msgsnd fails, at return ermo will be set to one of the following values 

eagain The message can't be sent due to themsg_qbytes limit for the queue and ipc_nowait was 

asserted in mgsf 1 g. 

eacces T he call ing process has no write access permissions on the message queue. 

efault Theaddresspointedtobymsgp isn't accessible 

eidrm The message queue was removed. 

eintr Sleeping on a full message queue condition, the process received a signal that had to be 

caught. 

einval Invalid ms q i d value ornonpositivemtype value or invalid msgsz value (less than 0 or greater 

than the system value msgmax). 

enomem The system has not enough memory to make a copy of the supplied msgbuf. 

W hen msgrcv fails, at return ermo will be set to one of the following values: 

e 2 big The message text length is greater than msgsz and msg_noerror isn't asserted in ms gf 1 g. 

eacces The call ing process has no read access permissions on the message queue 

efault Theaddresspointedtobymsgp isn't accessible 

eidrm Whiletheprocesswassleepingto receive a message, the message queue was removed. 

eintr Whiletheprocesswassleepingto receive a message, the process received a signal thathadto 

be caught. 

einval Illegal msggi d value or msgsz lessthan 0 . 

enomsg ipc_nowait was asserted in ms gf 1 g and no message of the requested type existed on the 

message queue 

NOTES 

The followings are system limits affecting a msgsnd system call: 

msgmax M aximum size for a message text; the implementation set this value to 4080 bytes. 

msgmnb Default maximum size in bytes of a message queue: policy dependent. The superuser can 

increasethesizeof a messagequeue beyond msgmnb byamsgcti system call. 

T he implementation has no intrinsic limits for the systemwide maximum number of message headers (msgtql) and for the 
systemwide maximum size in bytes of the message pool (msgpool). 
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SEE ALSO 

ipc(5), msgctl(2), msgget(2), msgrcv(2), msgsnd(2) 


Linux 0.99.13,1 November 1993 


msync 

msync— Synchronizes a file with a memory map 

SYNOPSIS 

#include <unistd.h> 

#include <sys/mman.h> 

#ifdef_POSIX_MAPPED_FILES 

#ifdef_POSIX_SYNCHRONIZED_IO 

int msync(const void ‘start, size_t length,int flags); 

#endif 

#endif 


DESCRIPTION 

msync flushes changes made to the in-corecopy of a file that was mapped into memory using mmap(2) back to disk. Without 
use of this call, there is no guarantee that changes are written back before munmap(2) is called. To be more precise, the part of 
the file that corresponds to the memory area starting at start and having length length is updated. Thef i ags argument may 
have the bits ms_async, ms_sync, and ms_invalidate set, but not both ms_async and ms_sync. ms_async specifies that an update 
be scheduled, but the call returns immediately. ms_sync asks for an update and waitsfor it to complete. ms_invalidate asks to 
invalidate other mappings of thesamefile (so that they can be updated with thefresh valuesjust written). 


RETURN VALUE 

On success, 0 is returned. On error, -1 is returned and errno isset appropriately. 

ERRORS 

einval start is not a multiple of pagesize, or any bit other than ms_async ] ms_invalidate \ 

ms_sync isset in flags. 

efault Theindicated memory (or part of it) wasnotmapped. 

C0NF0RMST0 

POSIX.4. 


SEE ALSO 

mma P (2), B.O. Gallmeister, POSIX.4, O’Reilly, pp. 128-129,389-391. 


Linux 1.3.86,12 April 1996 


munlock 

munlock— Reenables paging for some parts of memory 

SYNOPSIS 

ffinclude <sys/mman.h> 

int munlock(const void *addr, size_t len); 
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DESCRIPTION 

muniock reenables paging for the memory in the range starting at ad dr with length i en bytes. All pages that contain a part of 
thespecified memory range can after calling muniock be moved to external swap space again by the kernel. 

M emory locks do not stack, that is, pages that have been locked several times by calls to miock or miockaii will be unlocked 
by a single call to muniock for the corresponding rangeor by muniockaii. Pages that are mapped to several locationsorby 
several processes stay locked into RAM as long as they are locked at least at one location or by at least one process 
On POSIX systems on which miock and muniock are avai lable, _PO SIXM EM LOCK_RANGE is defined in <unistd.h> 
and the value pagesize from <iimits. h> indicates the number of bytes per page 

RETURN VALUE 

On success muniock returns 0 .0 n error, -1 is returned, errno is set appropriately, and no changes are made to any locks in 
the address space of the process 

ERRORS 

enomem Some of the specified address range does not correspond to mapped pages i n the address 

space of the process. 

einval 1 en wasnot a positive number. 

STANDARDS 

POSIX.lb, SVR4 

SEE ALSO 

mlock(2), mlockall(2), munlockall(2). 

Linux 1.3.43, 26 November 1995 


muniockaii 

muniockaii— Reenables paging for calling process 

SYNOPSIS 

#include <sys/mman.h> 
int munlockall(void); 

DESCRIPTION 

muniockaii reenables paging for all pages mapped into the address space of the calling process. 

M emory locks do not stack, that is, pages that have been locked several times by calls to miock or miockaii will be unlocked 
by a single call to muniockaii. Pages that are mapped to several locationsorby several processes stay locked into RAM as long 
as they are locked at least at one location or by at least one process. 

On POSIX systems on which miockaii and muniockaii are available, _posix_memlock isdefined in <uni std. h>. 

RETURN VALUE 

On success, muniockaii returns 0 .0 n error, -1 is returned and errno is set appropriately. 

STANDARDS 

POSIX.lb, SVR4 
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SEE ALSO 

mlockall(2), mlock(2), munlock(2) 


Linux 1.3.43, 26 November 1995 


nanosleep 

nanosieep- Pauses execution for a specified time 

SYNOPSIS 

#include <time.h> 

int nanosleep(const struct timespec *r eq, struct timespec *r em); 

DESCRIPTION 

nanosieep delays theexecution of the program for at least the time specified in * r eq .Thefunction can return earlier if a signal 
has been delivered to the process In this case it returns -i, setsermoto eintr, and writes the remaining time into the 
structure pointed to by rem unless rem is null. Thevalueof *rem can then be used to call nanosieep again and complete the 
specified pause 

The structure ti mespec is used to specify intervalsof time with nanosecond precision. It is specified in <t i me. h > and hasthe 
form 

struct timespec 

time_t tv_sec; /* seconds */ 
long tv_nsec; /* nanoseconds */ 


Thevalueof the nanoseconds field must be in the range 0 to 999 999 999. 

Compared to sieep(3) and usieep(3), nanosieep has the advantage of not affecting any signals; it is standardized by POSIX, it 
provides higher timing resolution, and it allows to continue a sleep that has been interrupted by a signal more easily. 

ERRORS 

In case of an error or exception, the nanosieep system call returns -i instead of 0 and setserrno to one of the following values: 
eintr The pause has been interrupted by a nonblocked signal that was delivered to the process 

The remaining sleep time has been written into *r e m so that the process can easily call 
nanosieep again and continue with the pause. 

einval The value in thetv_nsec field was not in the range 0 to 999 999 999 or t v_s ec wasnegative 

BUGS 

The current implementation of nanosieep is based on the normal kernel timer mechanism, which has a resolution of 1/HZ s 
(that is, lOmson Linux/i386 and lmson Linux/Alpha). Therefore, nanosieep pauses always for at least thespecified time; 
however, it can take up to 10ms longer than specified until the process becomes runnable again. For the same reason, the 
value returned in case of a delivered signal in *rem is usually rounded to the next larger multiple of 1/HZ s. 

Because some applications require much more precise pauses (for example in order to control sometime-critical hardware), 
nanosieep is also capable of short high-precision pauses If the process is scheduled under a real-time policy such as 
s c he d_ f 1 fo or schedjr, then pauses of up to 2ms will be performed as busy waits with microsecond precision. 

STANDARDS 

POSIX.lb 
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SEE ALSO 

sleep(3), usleep(3), sched_setscheduler(2), timer_create(2) 


Linux 1.3.85,10 April 1996 


nice 

nice- C hanges process priority 

SYNOPSIS 

#include <unistd.h> 


DESCRIPTION 

nice adds i nc to the priority for the calling PID. Note that only the superuser may specify a negative increment, or priority 
increase Note that internally, a higher number is a higher priority. Do not confusethis with the priority scheme as used by 
the nice interface. 

RETURN VALUE 

On success, 0 is returned. On error, -1 is returned and errno isset appropriately. 

ERRORS 

eperm A nonsuperuser attempts to do a priority increase a numerical decrease by supplying a 

negative i nc. 

C0NF0RMST0 

SVID EXT, AT&T, X/OPEN, BSD 4.3 

SEE ALSO 

nice(l), setpriority(2), fork(2), renice(8) 

Linux, 28March 1992 

oldfstat,oldlstat,oldstat,oldolduname,olduname 

oldfstat, oldlstat, oldstat, oldolduname, olduname— 0 bsolete system calls 

SYNOPSIS 

0 bsolete system calls. 

DESCRIPTION 

The Linux 1.3.6 kernel implements these calls to support old executables. These calls return structures that have grown since 
their first implementations, but old executables must continue to receive old smaller structures. 

Current executables should be linked with current libraries and never use these calls. 

SEE ALSO 

fstat(2), lstat(2), stat(2), uname(2), undocumented(2), unimplemented(2) 


Linux 1.3.6, 22July 1995 
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open, creat 

open, creat— Open and possibly create a file or device 

SYNOPSIS 


#include <sys/types.h> 



DESCRIPTION 

open attempts to open afileand return a file descriptor (a small, nonnegative integer for usein read, write, and so on), 
flags is one of o_rdonly, o_wronly, or o_rdwr, which request opening the file read-only, write-only, or read/write, respectively, 
flags may also bebitwise-ORed with one or more of the following: 
o_creat If the file does not exist it will be created. 

o_excl When used with o_creat, if thefile already exists, it is an error and the open will fail. Seethe 

"Bugs" section, though. 

o_noctty If pathname refersto aterminal device— see tty(4)— it will not become the process's 

controlling terminal even if the process does not have one 
o_trunc If thefile already exists, it will be truncated. 

o_append The file is opened in append mode. Initially, and before each write, thefile pointer is 

positioned at the end of thefile as if with lseek. 

o_nonblock or o_ndelay T hefile is opened in nonblocking mode N either the open nor any subsequent operations on 

the file descriptor that is returned will cause the calling process to wait. 
o_sync T he file is opened for synchronous I/O. Any writes on the resulting file descriptor will 

block the calling process until the data has been physically written to the underlying 
hardware Seethe "Bugs" section, though. 

Some of these optional flags can be altered using tcnti after the file has been opened. 

mode specifies the permissions to use if anewfileiscreated. It is modified by the process's mask in the usual way: The 
permission of the created file is (mode & "mask). 

Thefollowing symbolic constants are provided for mode: 

s_irwxu 00700 user (file owner) has read, write and execute permission. 

s_irusr (s_iread) 00400 user has read permission. 

s_iwusr (s_iwrite) 00200 user has write permission. 

s_ixusr (s_i exec) 00100 user has execute permission. 

s_irwxg 00070 group has read, write, and execute permission. 

s_irgrp 00040 group has read permission. 

s_iwgrp 00020 group has write permission. 

s_ixgrp 00010 group has execute permission. 

s_irwxo 00007 others have read, write, and execute permission. 

s_iroth 00004 others have read permission. 

s_iwoth 00002 others have write permission. 

s_ixoth 00001 others have execute permission. 

mode should always be specified when o_creat isin thet lags, and is ignored otherwise. 

creat is equivalent to open with f i ags equal to o_creat;o_wronly|o_trunc. 




Part II: System Calls 


816 


RETURN VALUE 

open and creat return the new file descriptor, or -i if an error occurred (in which caseerrno is set appropriately). Note that 
open can open device-special files, but creat cannot create them- use mknod(2) instead. 

ERRORS 

EEXIST 
EISDIR 
ETXTBSY 

EFAULT 
EACCES 

ENAMETOOLONG 
ENOENT 
ENOTDIR 
EMFILE 
ENFILE 
ENOMEM 
EROFS 
ELOOP 

ENOSPC 

C0NF0RMST0 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

BUGS 

o_sync is not currently implemented (asof Linux 0.99pl7). 

There are many infelicities in the protocol underlying N FS, affecting amongst otherso_SYNC, o_ndelay, and o_append. 
o_excl is broken on N FS filesystems; programs that rely on it for performing locking tasks will contain a race condition. The 
solution for performing atomic file locking using a lockfile is to create a unique file on the same f s (for example, incorporat¬ 
ing hostname and PID), use iink(2) to make a link to the lockfile and usestat(2) on the unique file to check if its link 
count has increased to 2 . D 0 not use the return value of the iink() call. 

SEE ALSO 

read(2), write(2), fcntl(2), close(2), unlink(2), mknod(2), stat(2), umask(2), mount(2), socket(2), socket(2), fopen(3), link(2) 

Linux0.99.7, 21 July 1993 


p a t h n a me already exists and o_creat and o_excl were used. 

pathname refersto a directory and the access requested involved writing. 

pat hname refersto an executable image which is currently being executed and write access 

was requested. 

pat hname points outside your accessi ble address space. 

The requested access to the file is not allowed, or one of the directories in pathname did not 
allow search (execute) permission, 
pathname WaStOO long. 

A directory component in pat hname does not exist or is a dangling symbolic link. 

A component used as a directory in pathname is not, in fact, a directory. 

T he process already has the maximum number of files open. 

The limit on the total number of files open on the system has been reached. 

I nsufficient kernel memory was available. 

p a t h n a me refersto a file on a read-only filesystem and write access was requested, 
pat hname contains a reference to a circular symbolic link, that is, a symbolic link whose 
expansion contains a reference to itself. 

pathname wasto be created but the device containing pat hname has no room for the new file. 


outb, outw, outl, outsb, outsw, outsl 

outb, outw, outl, outsb, outsw, outsl— Port output 

inb, inw, ini, insb, insw, insl— Port input 

outb_p, outw_p, outl_p, inb_p, inw_p, inl_p— Pause I/O 

DESCRIPTION 

This family of functions is used to do low-level port input and output. They are primarily designed for internal kernel use, 
but can be used from user space, given thefollowing information in addition to that given in outb(9). 








personality 




You compile with -o or -02 or something similar. The functions are defined as inline macros and will not be substituted in 
without optimization enabled, causing unresolved references at link time. 

You use ioperm(2) or alternatively iopi(2) to tell the kernel to allow the user space application to access the I/O ports in 
question. Failure to do this will cause the application to receive a segmentation fault. 

C0NF0RMST0 

outb and friends are hardware specific. The port and value arguments are in the opposite order from most DOS implementa¬ 
tions. 


SEE ALSO 

outb(9), ioperm(2), iopl(2) 


Linux, 29 Nmember 1995 


pause 

pause- Waits for signal 

SYNOPSIS 

#include <unistd.h> 
int pause(void); 

DESCRIPTION 

The pause system call causes the invoking process to sleep until a signal is received. 

RETURN VALUE 

pause always returns - 1 , and errno is set to erestartnohand. 

ERRORS 

eintr Signal was received. 

C0NF0RMST0 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

SEE ALSO 

kill(2), select(2), signal(2) 

Linux, 31 August 1995 


personality 

personality— Setsthe process execution domain 

SYNOPSIS 

int personality(unsigned long persona); 

DESCRIPTION 

Linux supports different execution domains, or personalities, for each process. Among other things, execution domains tell 
Linux how to map signal numbersinto signal actions. The execution domain system allows Linux to provide limited support 
for binaries compiled under other UN IX-like operating systems. 

personality will make the execution domain referenced by persona the new execution domain of the current process. 
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RETURN VALUE 

On success, persona ismadethenew execution domain andthepreviouspersona is returned. On error, -i is returned and 
emno is set appropriately. 


ERRORS 

einval persona doesnot referto a valid execution domain. 

FILE 

/usr/include/linux/personality.h 

C0NF0RMST0 

personality is Linux specific. 


Linux2.0, 22July 1996 


phys 

phys- Allows a process to access physical addresses (thiscommand is not implemented) 

SYNOPSIS 

int physflnt physnum, char ‘virtaddr,longsize, char *physaddr); 

DESCRIPTION 

Warning: Because this function is not implemented as of Linux 0.99.11, it will always return -i and sdt errno to enosys. 
phys maps arbitrary physical memory into a process's virtual address space, physnum isa number (0-3) that specifies which of 
the four physical spaces to set up. Up to four phys calls can be active at any one time virtaddr isthe process's virtual address 
size isthe number of bytes to map in. physaddr isthe physical address to map in. 

Valid virtaddr and physaddr values are constrained by hardware and must beat an address multiple of the resolution of the 
CPU's memory management scheme. If size is nonzero, size is rounded up to the next M M U resolution boundary. If size is 
0 , any previous phys(2) mapping for that physnum is nullified. 

RETURN VALUE 

On success, 0 is returned. On error, -1 is returned and errno isset appropriately. 

C0NF0RMST0 

version 7 AT&T UNIX 

BUGS 

phys is very machine dependent. 

SEE ALSO 

mmap(2), munmap(2) 


pipe 


Linux0.99.11, 24 July 1993 



profil 


819 


SYNOPSIS 

#include <unistd.h> 
int pipefint filedes[2]); 

DESCRIPTION 

pipe creates a pair of file descriptors, pointing to a pipe inode, and places them in the array pointed to by f iiedes. fiiedesm 
isfor reading, fiiedesm isfor writing. 

RETURN VALUE 

On success, 0 is returned. On error, -1 is returned and errno isset appropriately. 

ERRORS 

emfile T00 many file descriptors are in use by the process 

enfile Thesystem filetable isfull. 

efault f iiedes is not valid. 

SEE ALSO 

read(2), write(2), fork(2), socketpair(2) 

Linux0.99.11, 23July 1993 


profil 

prom— Execution time profile 

SYNOPSIS 

#include <unistd.h> 

int profil(char *buf, int buf s i z ,int offset ,int seal e); 

DESCRIPTION 

Under Linux 0.99.11, prom is not implemented in the kernel. Instead, the DLL 4.4.1 libraries provide a user-space 
implementation. 

but points to buf si z bytesof core Every virtual 10 milliseconds the user's program counter (PC) is examined: offset is 
subtracted and the result is multiplied by seal e. If this address is in buf, the word pointed to is incremented. 

If 5 cal e is less than 2 or buf si z iso, profiling is disabled. 

RETURN VALUE 

0 is always returned. 

BUGS 

profil cannot be used on a program that also uses itimer_prof itimers 
Calling profil with an invalid buf will result in acoredump. 

T rue kernel profiling provides more accurate results. 

SEE ALSO 

gprof(l), setitimer(2), signal(2), sigaction(2) 


Linux0.99.11, 23 July 1993 



Part II: System Calls 


820 


ptrace 

ptrace— Process trace 

SYNOPSIS 

#include <sys/ptrace.h> 

int ptrace(int request ,int pi d ,int addr ,int data); 


DESCRIPTION 


ptrace provides a means by which a parent process can control the execution of a child process and examine and change its 
core image. Its primary use isfor the implementation of breakpoint debugging. A traced process runs until a signal occurs. 
Then it stops and the parent is notified with wait(2). When the process is in the stopped state, its memory can be read and 
written. The parent can also cause the child to continue execution, optionally ignoring the signal which caused stopping. 
The value of the request argument determines the precise action of the system call: 


PTRACE_TRACEME 

PTRACE_PEEKTEXT, 

PTRACE_PEEKDATA 

PTRACE_PEEKUSR 

PTRACE_POKETEXT, 

PTRACE_POKEDATA 

PTRACE_POKEUSR 

PTRACE_SYSCALL, 

PTRACE_CONT 

PTRACE_KILL 

PTRACE_SINGLESTEP 

PTRACE_ATTACH 

PTRACE_DETACH 


This process isto be traced by its parent. The parent should be expecting to trace the child. 
Read word at location addr. 

Read word at location addr in the user area. 

Write word at location addr. 

Write word at location addr in the user area. 

Restart after signal. 

Send the child a sigkill to make it exit. 

Sdt the trap flag for single stepping. 

Attach to the process specified in pi d. 

D etach a process that was previously attached. 


NOTES 

init, the process with processID 1, may notusethisfunction. 

RETURN VALUE 

On success, 0 is returned. On error, -1 is returned and errno isset appropriately. 

ERRORS 

eperm T he specified process (that is, injt), cannot be traced or is already being traced. 

esrch The specified process does not exist. 

eio Request is not valid. 

C0NF0RMST0 

SVID EXT, AT&T,X/OPEN, BSD 4.3 

SEE ALSO 

gdb(l), exec(2), signal(2), wait(2) 


Linux 0.99.11, 23 July 1993 
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quotactl 

quotactl- M amputates disk quotas 

SYNOPSIS 

#include <sys/types.h> 

//include <sys/quota.h> 

int quotactl (int cmd, const char ‘special , intid , caddr_t addr); 

//include <linux/unistd.h> 

sysca!14(int, quotactl, int, cmd, const char *, special ,int, id, caddr_t, addr); 


DESCRIPTION 

The quota system definesforeach user or group a soft limit and a hard limit bounding the amount of disk space that can be 
used on agiven filesystem. The hard limit cannot be crossed. The soft limit can be crossed, but warningswill ensue. 

M oreover, the user cannot be above the soft limit for more than one week (by default) at a time After this week the soft limit 
countsasa hard limit. 


The quotactl system call manipulates these quotas. Its first argument isoftheform 
QCMD(subcmd.type) 


where type iseither usrquota or grpquota (for user quota and group quota, respectively. 

Thesecond argument special isthe block special device these quotas apply to. It must be mounted. 
The third argument ID is the user or group ID these quotas apply to (when relevant). 


The fourth argument, addr , is the address of a data structure depending on the command. 
The subcmd is one of the following: 


Q_QU0TA0N 

Q_QU0TA0FF 

Q_GETQUOTA 

Q_SETQUOTA 

Q_SETQLIM 

Q_SETUSE 

Q_SYNC 

Q_GETSTATS 


Enables quotas Theaddr argument is the pathname of the file containing the quotas for the filesystem. 
Disables quotas. 

Gets limits and current usage of disk space. Theaddr argument is a pointer to a dqbik structure 
(defined in <sys/quota.h>). 

Sdts limits and current usage: addr isas before 
Sdtslimits: addr isasbefore. 

Sdts usage. 

Syncsdisk copy of a filesystem's quotas. 

Gets collected stats. 


RETURN VALUE 

On success quotactl returns 0 . On error, -i is returned and errno is set appropriately. 

ERRORS 

enopkg The kernel was compiled without quota support. 

efault Bad addr value. 

einval type is not a known quota type 0 r special could not be found. 

enotblk special is not a block special device. 

enodev special cannot befound in the mount table 

eacces The quota file is not an ordinary file 

eio Cannot read or write the quota file 

emfile Too many open files C annot open quota file 
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EBUSY 

ESRCH 

EPERM 

CONFORMSTO 

BSD 


read 

read- Reads from a file descriptor 

SYNOPSIS 

#include <unistd.h> 

DESCRIPTION 

reado attempts to read up to count bytes from file descriptor fd into the buffer starting at but. 

If count iso, reado returns 0 and has no other results If count isgreater than ssize_max, theresult is unspecified. 

RETURN VALUE 

On success the number of bytes read is returned (0 indicates end of file) and thefile position is advanced by this number. It 
is not an error if this number is smaller than the number of bytes requested; this may happen, for example, because fewer 
bytes are actually available right now (maybe because we were close to end-of-file or because we are reading from a pipe or 
from a terminal), or because reado was interrupted by a signal. On error, -1 is returned and errno is sdt appropriately. In this 
case it is left unspecified whether the file position (if any) changes 

ERRORS 

eintr The call was interrupted by a signal before any data was read. 

eagain Non-blocking I/O has been selected using o_nonblock and no data was immediately availablefor 

reading. 

eio I/O error. This will happen, for example when the process is in a background processgroup, tries to 

read from its controlling tty, and it is ignoring or blocking sigttin or its processgroup isorphaned. 
eisdir fd refersto a directory. 

ebadf fd is not a valid file descriptor or is not open for reading. 

einval fd is attached to an object that is unsuitable for reading. 

efault buf isoutside your accessible address space. 

Other errors may occur, depending on the object connected to fd. PO SIX allows a read that is interrupted after reading some 
data to return -1 (with errno set to eintr) or to return the number of bytes already read. 

CONFORMSTO 

SVID, AT & T, PO SIX, X/O PEN , BSD 4.3 

SEE ALSO 

readdir(2), write(2), write(2), fcntl(2), close(2), lseek(2), select(2), readlink(2), ioctl(2), fread(3) 

Linux, 17 January 1996 


q_quotaon was asked, but quota were enabled already. 

q_getquota or q_setquota or q_setuse or q_setqlim was asked for a filesystem that didn't have quota 


T he process was not root (for the filesystem), and q_getquota was asked for another ID than that of the 
process itself, or anything other than q_getstats or q_sync was asked. 


Linux 1.3.88,14 April 1996 
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readdin 

readdir— Reads directory entry 

SYNOPSIS 

#include <unistd.h> 

#include <linux/dirent.h> 
ffinclude <linux/unistd.h> 

syscall3(int, readdir, uint, fd, struct dirent *, dirp, uint, count); 
int readdir(unsigned int fd, struct dirent *dirp, unsigned int count); 

DESCRIPTION 

This is not the function you are interested in. Look at readdir(3) for the PO SIX-conforming C library interface. This page 
documents the bare kernel system call interface which can change, and which issuperseded by getdents(2). 
readdir reads one dirent structure from the directory pointed at by fd into the memory area pointed to by d r p . T he 
parameter count is ignored; at most one dirent structure is read. 

The dirent structure is declared asfollows 

/* inode number */ 

/* offset to this dirent */ 

/* length of this d_name */ 

/* file name (null-terminated) */ 

d.i no isan inode number, d.off is the distance from the start of the directory to this dirent. d.reci en isthe size of d_ name, not 
counting the null terminator, d.name isa null-terminated filename 

RETURN VALUE 

On success, i is returned. On end of directory, 0 is returned. On error, -1 is returned and errno isset appropriately. 

ERRORS 

ebadf Invalid file descriptor fd. 

enotdir Filedescriptor does not refer to a directory. 

C0NF0RMST0 

Thissystem call is Linux specific. 

SEE ALSO 

getdents(2), readdir(3) 

Linux 1.3.6, 22 July 1995 


long d_ino; 
off_t d_off; 

unsigned short d_reclen; 
char d_name [NAME_MAX+1]; 


readlink 

readlink- Reads value of a symbolic link 

SYNOPSIS 

ffinclude <unistd.h> 

int readlink(const char ‘path, char *buf , size_t bufsiz); 
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DESCRIPTION 

readiink places the contents of the symbolic link path in the buffer buf, which has sizebuf si z . Readlink does not append a 
nul character to buf. 

RETURN VALUES 

Thecall returns the count of characters placed in the buffer if it succeeds, or a-i if an error occurs, placing the error code in 
the global variable ermo. 

ERRORS 

ENOTDIR 
EINVAL 

ENAMETOOLONG 

ENOENT 
EACCES 
ELOOP 
EINVAL 
EIO 

EFAULT 

HISTORY 

The readiink function call appeared in BSD 4.2. 

SEE ALSO 

stat(2), lstat(2), symlink(2) 

BSD Man Page 24July 1993 


A component of the path prefix is not a directory. 

T he pathname contains a character with the high-order bit set. 

A component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 
characters. 

The named file does not exist. 

Search permission is denied for a component of the path prefix. 

Too many symbolic linkswere encountered in translating the pathname 
T he named file is not a symbolic link. 

An I/O error occurred while reading from thefilesystem. 
buf extends outside the process's allocated address space. 


readv,writev 

readv, writev- Reads or writes a vector 

SYNOPSIS 

ffinclude <sys/uio.h> 

int readv(int fd, const struct lovec * vector, size_t count); 
int writev(int fd, const struct iovec * vector , size_t count ); 
struct iovec { 

ptr_t i ov_ba s e ; /* Starting address. */ 
size_t iov_I en ; /* Length in bytes. */ 


DESCRIPTION 

readv readsdata from file descriptor f d and puts the result in the buffers described by vect or .The number of buffers is 
specified by count . The buffers are filled in the order specified. Operates just like read except that data is put in vector 
instead of a contiguous buffer. 

writev writes data to file descriptor f d, and from the buffers described by vector. T he number of buffers is specified by c o u n t. 
The buffers are used in the order specified. Operates just like write except that data is taken from vector instead of a 
contiguous buffer. 
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RETURN VALUE 

On success, readv returnsthe number of bytes read. 0 n success, writev returnsthe number of bytes written. On error, -i is 
returned, and errno isset appropriately. 

ERRORS 

einval An invalid argument was given. For instance count might be greater than max_iovec, or 0 . f d could 

also be attached to an object that is unsuitable for reading. 

efault Segmentation fault. M ost likely vector orsomeof the i o*_base pointers pointsto memory that is 

not properly allocated. 

ebadf Thefiledescriptor fd isnotvalid. 

eintr Thecall was interrupted by a signal before any data was read/written. 

eagain Non-blocking I/O has been selected using o_nonblock and no data was immediately availablefor 

reading. (Or thefile descriptor fd isforan object that is locked.) 
eisdir t d refers to a directory. 

eopnotsup td refersto a socket or devicethat does not support reading/writing. 

0 ther errors may occur, depending on the object connected to f d . 

SEE ALSO 

read(2), write(2), fprintf(3), fscanf(2) 

Linux 1.3.86,12 April 1996 


reboot 

reboot— Reboots or disables Ctrl-lAlt-tO el 

SYNOPSIS 

ffinclude <unistd.h> 

int reboot (int magic.int magi c _ t o o,int flag); 

DESCRIPTION 

reboot reboots the system orenables^disablesCAD. 

If magic = 0 xfeeidead and magic_too = 672274793 , the action performed will be based on f I ag. 
If fiag=8xi 234567 , a hard reset is performed. 

If fiag=0x89abcdet, CAD is enabled. 

If fiag=8, CAD is disabled and a signal is sent to process ID 1. 

N Ote that reboot () does not sync o! 

0 nly the superuser may use thisfunction. 

RETURN VALUE 

On success, 0 is returned. On error, -i isreturned, andermo is set appropriately. 

ERRORS 

einval Bad magic numbers or f i ag. 

eperm A non-root user has attempted to call reboot. 
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CONFORMSTO 

reboot is Linux specific. 

SEE ALSO 

sync(2), ctrlaltdel(8), halt(8), reboot(8) 

Linux0.99.10, 28 Ward) 1992 


recv,recvfrom,recvmsg 

recv, recvfrom, recvmsg- Receives a message from a socket 

SYNOPSIS 

#include <sys/types.h> 

//include <sys/socket.h> 

int recv(int s, void *buf , intlen, unsigned int flags); 
int recvfrom(int s, void*buf , int len, unsigned int flags, 
struct sockaddr ‘from, int *fromlen); 
int recvmsgfint s, struct msghdr *msg , unsigned int flags); 

DESCRIPTION 

Warning:ThisisaBSD man page As of Linux 0.99.11, recvmsg was not implemented. 

recvfrom and recvmsg are used to receive messages from a socket, and may be used to receive data on a socket whether or not 
it isconnection oriented. 

If f rom is non-nil, and the socket is not connection-oriented, the source address of the message is filled in. f romi en is a value- 
result parameter, initialized to the size of the buffer associated with from and modified on return to indicate the actual size of 
the address stored there. 

The recv call is normally used only on a connected socket (seeconnect(2)) and is identical to recvfrom with anil from 
parameter. Because it is redundant, it might not be supported in future releases. 

All three routines return the length of the message on successful completion. If a message is too long to fit in the supplied 
buffer, excess bytes might be discarded depending on the type of socket from which the message is received (see socket(2)). 

If no messages are available at the socket, the receive call waits for a message to arrive- unless the socket isnonblocking (see 
fcnti(2)), in which case the value-i is returned and the external variable errno is set to ewouldblock. T he receive calls 
normally return any data available, up to the requested amount, rather than wait for receipt of thefull amount requested; 
this behavior is affected by the socket-level options so_rcvlowat and so_rcvtimeo, described in getsockopt(2). 

The seiect(2) call maybe used to determine when more data arrives. 

T he f i ags argument to a recv call isformed by oringoneormoreofthevalues: 
msg_oob Process out-of-band data 

msg_peek Peek at incoming message 

msg_waitall W ait for full request or error 

ThewsG_ooBflag requests receipt of out-of-band data that would not be received in the normal data stream. Some protocols 
place expedited data at the head of the normal data queue; thus this flag cannot be used with such protocols. The msg_peek 
flag causes the receive operation to return data from the begi nning of the receive queue without removing that data from the 
queue; thus, a subsequent receive call will return the same data. ThewsGj/AiTALL flag requests that the operation block until 
thefull request is satisfied. However, the call might still return less data than requested if a signal iscaught, an error or 
disconnect occurs, or the next data to be received is of a different type than that returned. 
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The recvmsg call usesamsghdr structure to minimize thenumber of directly supplied parameters Thisstructurehasthe 
following form, as defined in sys/socket.h: 
struct msghdr { 

caddr_t msg_name; /* optional address */ 
u_int msg_namelen; /* size of address */ 
struct iovec *msg_iov; /* scatter/gather array */ 
u_int msg_iovlen; /* # elements in msg_iov */ 
caddr_t msg_control; /* ancillary data, see below */ 
u_int msg_controllen; /* ancillary data buffer len */ 
int msg_flags; /* flags on received message */ 

H ere msg_name and msg_nameien specify the destination address if the socket is unconnected; msg_namemay be given asanull 
pointer if no names are desired or required. msg_iov and msg_iovien describe scatter gather locations, as discussed in read(2). 
msg_controi, which has length msg_controiien, points to a buffer for other protocol control-related messages or other 
miscellaneous ancillary data. T he messages are of the form 

struct cmsghdr { 

u_int cmsg_len; /* data byte count, including hdr */ 
int cmsg_level; t* originating protocol */ 
int cmsg_type; /* protocol-specific type */ 

/* followed by 

u_char cmsg_data[]; */ 

}; 

You could use this, for example to learn of changes in the data stream in XNS/SPP, or in ISO, to obtain user- 
connection-request data by requesting a recvmsg with no data buffer provided immediately after an accept call. 

0 pen file descriptors are now passed as ancillary data for af_unix domain sockets, with cmsg_ievei set to sol_socket and 
cmsg_type Set to SCM_RIGHTS. 

Themsg_fiags field isset on return according to the message received. msg_eor indicatesend-of-record; thedata returned 
completed a record (generally used with sockets of type sock_seqpacket). msg_trunc indicates that the trailing portion of a 
datagram was discarded because the datagram was larger than the buffer supplied. msg_ctrunc indicatesthat some control 
data was discarded due to lack of space in the buffer for ancillary data. msg_oob is returned to indicate that expedited or out- 
of-band data was received. 

RETURN VALUES 

These calls return the number of bytes received, or -i if an error occurred. 

ERRORS 

EBADF 
ENOTCONN 

ENOTSOCK 
EWOULDBLOCK 

EINTR 
EFAULT 

HISTORY 

These function callsappeared in BSD 4.2. 


The argument s isan invalid descriptor. 

The socket is associated with a connection-oriented protocol and has not been connected (see 

connect(2) and accept(2)). 

The argument s does not refer to a socket. 

T he socket is marked non-blocking, and the receive operation would block, or a receive timeout 
had been set, and the timeout expired before data was received. 

The receive was interrupted by delivery of a signal before any data was available 
The receive buffer pointer(s) point outside the process's address space 
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rename 

rename— C hangs the name or location of a file 

SYNOPSIS 



DESCRIPTION 

rename renamsafile, moving it between directories if required. 

Any other hard links to thefile (as created using link) are unaffected. 

If newpath already exists it will be automatically overwritten (subject to a few conditions-seethe "Errors" section), so that 
there is no point at which another process attempting to access newpat h will find it missing. 

If newpath exists but the operation fails for some reason or the system crashes, rename guarantees to leave an instance of 
newpath in place. 

However, when overwriting there will probably be a window in which both o i dpath and newpath refer to thefile being 
renamed. 

If o i dpath refers to a symbolic link, the link will be renamed; if newpath refers to a symbolic link, the link will be overwritten. 

RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 


ERRORS 

eisdir newpath isan existing directory, but oi dpat h is not a directory. 

exdev oi dpath and newpath are not on thesamefilesystem. 

enotempty newpath is a non-empty directory. 

ebusy newpath exists and isthecurrent working directory or root directory of some process 

einval An attempt was madeto make a directory a subdirectory of itself. 

emlink oi dpath already has the maximum number of links to it, or it wasa directory and the directory 

containing newpath has the maximum number of links. 
enotdir Acomponentusedasadirectoryinoidpath or newpat h is not, in fact, a directory. 

efault oi dpath or newpat h pointsoutsideyouraccessibleaddressspace 

eacces W rite access to the directory containing oi dpath or newpat h is not allowed for the process's effective 

U ID, or one of the directories in oi dpath or newpath did not allow search (execute) permission, or 
oi dpath was a directory and did not allow write permission (needed to update the.. entry). 
eperm The directory containing oi dpath has the sticky bit set, and the process's effective UID is neither the 

UID of thefile to be deleted nor that of the directory containing it, or the filesystem containing 
pa t h n a me does not support renam i ng of the type requested. 

ENAMETOOLONG ol dpath Or newpath WaStOO long. 

enoent A directory component in 01 dpath or newpath does not exist or is a dangling symbolic link. 

enomem Insufficient kernel memory was available. 

erofs Thefileison a read-only filesystem. 






rmdir 


eloop oi dpat h or newpat h containsa referenceto a circular symbolic link; that is, a symbolic link whose 

expansion containsa referenceto itself. 

enospc The device containing the file has no room for the new directory entry. 

C0NF0RMST0 

POSIX, BSD 4.3, ANSI C 

BUGS 

C urrently (Linux 0.99pl7), most of thefilesystemsexcept M inix will not allow any overwriting renames involving directories. 
You get eexist if you try. 

On N FS filesystems, you cannot assume that just because the operation failed, the file was not renamed. If the server does 
the rename operation and then crashes, the retransmitted RPC, which will be processed when the server isup again, causesa 
failure. The application isexpected to deal with this. See iink(2) for a similar problem. 

SEE ALSO 

link(2), unlink(2), symlink(2), mv(l), link(8) 

Linux0.99.7, 24July 1993 


rmdir 

rmdir— D eletes a directory 

SYNOPSIS 

#include <unistd.h> 

int rmdir(const char ‘pathname); 


DESCRIPTION 

rmdir deletes a directory, which must be empty. 

RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 

ERRORS 

eperm Thefilesystem containing pathname does not support the removal of directories 

efault pathname pointsoutsideyouraccessibleaddressspace. 

eacces W rite access to the directory contai ni ng p a t h n a me was not allowed for the process's effective UID, 

oroneofthedirectoriesin pathname did notallow search (execute) permission. 
eperm Thedirectory containing pathname has the sticky bit (s_isvtx) set, and the process's effective U I D is 

neither theUID ofthefileto be deleted nor that of thedirectory containing it. 

ENAMETOOLONG p a t h n a me Was tOO long. 

enoent A directory component in pat hname does not exist or isa dangling symbolic link. 

enotdir pat hname, or a component used as a directory in pat hname, is not, in fact, a directory. 

enotempty pathname containsentriesotherthan . and ... 

ebusy pathname isthecurrent working directory or root directory of some process 

enomem Insufficient kernel memory was available. 

erofs pathname refersto afileon a read-only filesystem. 

eloop pathname containsa reference to a circular symbolic link; that is, a symbolic link containing a 

referenceto itself. 
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CONFORMSTO 

SVID, AT&T, POSIX, BSD 4.3 

BUGS 

Infelicities in the protocol underlying N FScan cause the unexpected disappearance of directories that are still being used. 

SEE ALSO 

rename(2), mkdir(2), chdir(2), unlink(2), rmdir(l), rm(l) 

Linux0.99.7, 24July 1993 

sched_get_priority_max, sched_get_priority_min 

sched_get_priority_max, sched_get_priority_rain— Gets Static priority range 

SYNOPSIS 

#include <sched.h> 

int sched_get_priority_max(int policy); 
int_sched_get_priority_min(int poli cy); 

DESCRIPTION 

sched_get_priority_max returnsthe maximum priority value that can be used with the scheduling algorithm identified by 
poi icy. sched_get_priority_min returnsthe minimum priority value that can be used with the scheduling algorithm 
identified by poi i cy. Supported poi i cy values are sched_fifo, sched_rr, and sched_other. 

Processes with numerically higher priority values are scheduled before processes with numerically lower priority values. 
Therefore the value returned by sched_get_priority_max will be greater than the value returned by sched_get_priority_min. 
Linux allows the static priority value range 1 to 99 for sched_fifo and sched_rr, and the priority 0 for sched_other. 
Scheduling priority ranges for the various policies are not alterable. 

The range of scheduling priorities may vary on other PO SIX systems, so it is a good idea for portable applications to use a 
virtual priority range and map it to the interval given by sched_get_prionty_max and sched_get_priority_min. POSIX. lb 
requires a spread of at least 32 between the maximum and the minimum values for sched_fifo and sched_rr. 

POSIX systems on which sched_get_priority_max and sched_get_priority_min are available define 
_POSIX_PRIORITY_SCHEDULING in <unistd.h>. 

RETURN VALUE 

On success, sched_get_priorityjnax and sched_get_priority_min return the maximum and minimum priority valuesforthe 
named scheduling policy. On error, -i isreturned, and ermo isset appropriately. 

ERRORS 

einval The parameter policy does not identify a defined scheduling policy. 

STANDARDS 

POSlX.lb (formerly POSIX.4) 

SEE ALSO 

sched_setscheduler(2), sched_getscheduler(2), sched_setparam(2), sched_getparam(2) 

sched_setscheduier(2) has a description oftheLinux scheduling scheme. 
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Programming for the Real World- P0SIX.4 by Bill 0. Gallmeister, O’Reilly & Associates, Inc., ISBN 1-56592-074-0 
IEEE Std 1003.lb-1003 (PO SIX.lb standard) 

I SO/I EC 9945-1:1996 

Linux 1.3.81,10 April 1996 


sched_rr_get_interval 

sohed_rr_get_intervai—Gets the sched_rr interval for the named process 

SYNOPSIS 

#include <sched.h> 

int sched_rr_get_interval(pid_t pid, struct timespec *tp); 
struct timespec { 

time_t tv_sec; /* seconds */ 
long tv_nsec; /* nanoseconds */ 


DESCRIPTION 

sched_rr_get_intervai writes into thet i mespec structure pointed to by t p the round-robin time quantum for the process 
identified by pi t. If pi d iso, the time quantum for the calling process is written into *tp. The identified process should be 
running under the sched_rr scheduling policy. 

The round robin time quantum value is not alterable under Linux 1.3.81. 

POSIX systems on which sched_rr_get_intervai is available define _posix_priority_scheduling in <unistd.h>. 

RETURN VALUE 

On success, sched_rr_get_tntervai returns 0.0 n error, -i is returned, and errno isset appropriately. 

ERRORS 

esrch The process whose ID is p i d could not be found. 

enosys The system call is not yet implemented. 

STANDARDS 

POSlX.lb (formerly POSIX.4) 

BUGS 

As of Linux 1.3.81, sched_m_get_intervai returns with error enosys, because sched_rr has not yet been fully implemented or 
tested properly. 

SEE ALSO 

sched_setscheduier(2) has a description of the Linux scheduling scheme. 

Programming for theReal World-POSIX.4 by Bill 0. Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0 
IEEE Std 1003.lb-1993 (POSlX.lbstandard) 

ISO/I EC 9945-1:1996 


Linux 1.3.81,10 April 1996 
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schedjetparam, schedjetparam 

sched_setparam, sched_getparam— Sets and get scheduling parameters 

SYNOPSIS 

#include <sched.h> 

int sched_setparam(pid_t pid, const struct sched_param *p); 
int sched_getparam(pid_t pid, struct sched_param *p ); 
struct sched_param { 


DESCRIPTION 

sched_setparam sets the scheduling parameters associated with the scheduling policy for the process identified by pi d . If pi d is 
0, the parameters of the current process are set. The interpretation of the parameter p dependson the selected policy. 
Currently, the following three scheduling policies are supported under Linux: sched_fifo, sched_rr, and sched_other. 
sched_getparam retrieves the scheduling parametersfor the process identified by pi d. If pi d iso, the parameters of the current 
process are retrieved. 

sched_setparam checksthe validity of p for thescheduling policy of the process The parameter p->sched_priority must lie 
within the range given by sched_get_priority_min and sched_get_priority_max. 

POSIX systems on which sched_setparam and sched_getparamareavailabledefine_posix_PRioRiTY_scHEDULiNG in <umstd.h>. 

RETURN VALUE 

On success, sched_setparam and sched_getparam return 0.0 n error, -i is returned, and errno is set appropriately. 

ERRORS 

esrch The process whose ID ispi d could not befound. 

eperm The calling process does not have appropriate privileges The process calling sched_setparam needs 

an effective UID equal to the UID or UID of the process identified by p i d, or it must be a 
superuser process. 

einval Theparameterp doesnotmakesenseforthecurrentschedulingpolicy. 

STANDARDS 

POSlX.lb (formerly POSIX.4) 

SEE ALSO 

sched_setscheduler(2), sched_getscheduler(2), sched_get_priority_max(2), sched_get_priority_min(2), nice(2), 
setpriority(2), getpriority(2) 

sched_setscheduier(2) has a description oftheLinux scheduling scheme. 

Programming for theReal World-POSIX.4 by Bill 0. Gallmeister, O'Reilly & Associates Inc., ISBN 1-56592-074-0 
IEEE Std 1003.lb-1993 (POSlX.lbstandard) 

ISO/I EC 9945-1:1996 


Linux 1.3.81,10 April 1996 
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sched_setscheduler,sched_getscheduler 

sched_setscheduier, sched_getscheduier— Sets and gets scheduling algorithm/parameters 

SYNOPSIS 

#include <sched.h> 

int sched_setscheduler(pid_t pi d,intpo I icy , const struct sched_param *p ); 
int sched_getscheduler(pid_t pid); 
struct sched_param { 


DESCRIPTION 

sched_setscheduier sets both the scheduling policy and the associated parameters for the process identified by pi d . If pi d is 0, 
the scheduler of the calling process will beset. The interpretation of the parameter p depends on the selected policy. 
Currently, the following three scheduling policies are supported under Linux: sched_fifo, sched_rr, and sched_other; their 
respective semantics are described in thefollowing section. 

sched_getscheduier queries the scheduling policy currently applied to the process identified by pi d. If pi d is 0 , the policy of 
thecalling processwill be retrieved. 

SCHEDULING POLICIES 

The scheduler is the kernel part that decides which runnable processwill be executed next by the CPU. The Linux scheduler 
offers three different scheduling policies, one for normal processes and two for real-time applications A static priority value, 
sched.pri or i ty, is assigned to each process and this value can be changed only viasystem calls Conceptually, the scheduler 
maintains a list of runnable processes for each possibles ched.pri or i t y value, and sched_pri ori ty can have a value in the 
range 0 to 99. T0 determine the process that runs next, the Linux scheduler looks for the non-empty list with the highest 
static priority and takes the process at the head of this list. The scheduling policy determines for each process, where it will 
be inserted into the list of processes with equal static priority and how it will move inside this list. 
sched_other is the default universal time-sharing scheduler policy used by most processes sched_fifo and sched_rr are 
intended for special, time-critical applicationsthatneed precise control over the way in which runnable processes are selected 
for execution. Processes scheduled with sched_other must be assigned the static priority 0; processes scheduled under 
sched_fifo or sched_rr can have a static priority in the range 1 to 99.0 nly processes with superuser privileges can get a static 
priority higher than 0 and can therefore be scheduled under sched_fifo or sched_rr. The system calls sched_get_priority_min 
and sched_get_priority_max can be used tofind out the valid priority range for a scheduling policy in aportable way on all 
PO SIX.lb-conforming systems 

All scheduling is preemptive: If a process with a higher static priority gets ready to run, the current processwill be preempted 
and returned into its wait list. The scheduling policy determines the ordering within the list of runnable processes only 
among those with equal static priority. 

SCHEDJIFO: FIRST IN-FIRST OUT SCHEDULING 

sched_fifo can only be used with static priorities higher than 0, which meansthat when a sched_fifo process becomes 
runnable, it will always preempt immediately any currently running normal sched_other process. sched_fifo isa simple 
scheduling algorithm without time slicing. 

For processes scheduled under the sched_fifo policy, the following rules are applied: A sched_fifo process that has been 
preempted by another processof higher priority will stay at the head of the list for its priority and will resume execution as 
soon asall processes of higher priority are blocked again. When a sched_fifo process becomes runnable, it will be inserted at 
the end of the list for its priority. A call to sched_setscheduier or sched_setparam will put thescHED_FiF0 process identified by 
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pi d at the end of the list if it was runnable A process calling sched_yieid will be put at the end of the list. N o other events 
will move a process scheduled under the sched_fifo policy in the wait list of runnable processes with equal static priority. A 
sched_fifo process runs until it is blocked by an I/O request, it ispreempted by a higher-priority process, or it calls 

sched_yield. 

SCHED RR: ROUND-ROBIN SCHEDULING 

sched_rr is a simple enhancement of sched_fifo. Everything described in the preceding section for sched_fifo also applies to 
sched_rr, except that each process is only allowed to run for a maximum time quantum. If a sched_rr process has been 
running for a time period equal to or longer than the time quantum, it will be put at the end of the list for its priority. A 
sched_rr process that has been preempted by a higher-priority process and subsequently resumes execution asa running 
process will complete the unexpired portion of its round-robin time quantum. The length of the time quantum can be 
retrieved by sched_rr_get_interval. 

SCHED OTHER: DEFAULT LINUX TIME-SHARING SCHEDULING 

sched_other can only be used at static priority 0. sched_other is the standard Linux time-sharing scheduler that is intended 
for all processes that do not require special static-priority real-time mechanisms The process to run ischosen from the static 
priority 0 list based on adynamic priority that is determined only inside this list. The dynamic priority is based on the nice 
level (set by the nice or setpriority system call) and is increased for each time quantum the process is ready to run but is 
denied to run by the scheduler. Thisensures fair progress among all sched_other processes 

RESPONSE TIME 

A blocked high-priority process waiting for the I/O has a certain response time before it is scheduled again. The device driver 
writer can greatly reduce this response time by using a 4ow interrupt interrupt handler, asdescribed in request trq(9). 

MISCELLANEOUS 

C hild processes inherit the scheduling algorithm and parameters across a fork. 

M emory locking is usually needed for real-time processes to avoid paging delays; this can be done with miock or miockaii. 
Because a non-blocking endless loop in a process scheduled under sched_fifo or sched_rr will block all processes with lower 
priority forever, a software developer should always keep available on the console a shell scheduled under a higher static 
priority than the tested application. This will allow an emergency kill of tested real-time applicationsthat do not block or 
terminate as expected. Because sched_fifo and sched_rr processes can preempt other processes forever, only root processes 
are allowed to activate these policies under Linux. 

POSIX systems on which sched_setscheduier and sched_getscheduierareavailabledefine_posix_PRioRiTY_scHEDULiNG in 

RETURN VALUE 

On success, sched_setscheduier returns 0.0 n success, sched_getscheduier returns the policy for the process (a non-negative 
integer). On error, -i is returned, and errno is set appropriately. 

ERRORS 

ESRCH 
EPERM 

EINVAL 

STANDARDS 

POSlX.lb (formerly POSIX.4) 


The process whose ID ispid could not be found. 

The calling process does not have appropriate privileges Only root processes are allowed to activate 
the sched_fifo and sched_rr policies. The process calling sched_setscheduier needs an effective 
UID equal to the EU ID orUID of the process identified by pi d, or it must be a superuser process. 
T he scheduling policy is not one of the recognized policies, or the parameter p does not make sense 
for the policy. 



BUGS 

As of Linux 1.3.81, sched_rr has not yet been tested carefully and might not behave exactly as described or required by 
POSlX.lb. 

SEE ALSO 

sched_setparam(2), sched_getparam(2), sched_yield(2), sched_get_priority_max(2), sched_get_priority_min(2), nice(2), 
setpriority(2), getpriority(2), mlockall(2), nuinlockall(2), mlock(2), munlock(2). 

Programming for the Real World-POSIX.4 by Bill 0. Gallmeister, O’Reilly & Associates, Inc., ISBN 1-56592-074-0 
IEEE Std 1003.lb-1003 (POSlX.lbstandard) 

ISO/I EC 9945-1:1996-This isthe new 1996 revision of POSIX.1, which contains in one single standard PO SIX.1(1990), 
POSIX.lb(1993), POSIX.lc(1995), and POSIX.li(1995). 

Linux 1.3.81,10 April 1996 


sched_yield 

sched_yieid— Yields the processor 

SYNOPSIS 

#include <sched.h> 

DESCRIPTION 

A process can relinquish the processor voluntarily without blocking by calling sched_yieid. The process will then be moved 
to the end of the queue for its static priority and a new process gets to run. 

Note: If the current process is the only process in the highest priority list at that time this process will continue to run after a 
call to sched_yield. 

POSIX systems on which sched_yieid isavailable define _posix_priority_scheduling in <unistd.h>. 

RETURN VALUE 

On success, sched_yieid returns 0 .0 n error, -i is returned, and errno is set appropriately. 

STANDARDS 

POSlX.lb (formerly POSIX.4) 

SEE ALSO 

sched_setscheduier(2) for a description of Linux scheduling 

Programming for the Real World-POSIX.4 by Bill 0. Gallmeister, O’Reilly & Associates, Inc., ISBN 1-56592-074-0 
IEEE Std 1003.lb-1993 (POSlX.lbstandard) 

ISO/I EC 9945-1:1996 

Linux 1.3.81,10 April 1996 


select, FD_CLR, FD_ISSET, FD_SET,FD_ZER0 

select, fd_clr, fd_isset, fd_set, fd_zero — Synchronous I/O multiplexing 
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SYNOPSIS 

#include <sys/time.h> 

//include <sys/types.h> 

#include <unistd.h> 

int select(int n,fd_set *r e a d fds ,fd_set *wr i tefds ,fd_set *exceptfds, 
struct timeval ‘timeout); 

FD_CLR(int fd,fd_set *set); 

FD_ISSET(int fd,fd_set *set); 

FD_SET(int fd,fd_set *set); 

FD_ZERO(fd_set ‘set ) 

DESCRIPTION 

select waits for a number of file descriptors to change status 

Three independent sdts of descriptors are watched. Those listed in readfds will be watched to see if characters become 
available for reading, those in wri t et ds will be watched to see if it isokayto immediately write on them, and those in 
except tds will be watched for exceptions 0 n exit, the s&s are modified in place to indicate which descriptors actually 
changed status 

Four macros are provided to manipulate the sets. fd_zero will clear a set. fd_set and fd_clr add or remove a given descriptor 
from a si. fd_isset tests to see if a descriptor is part of theset; this is useful after select returns 
n is the highest-numbered descriptor in any of the three sets plus 1. 

t i meout isan upper bound on the amount of time elapsed before select returns It may be 0, which causes select to return 
immediately. If timeout is null (no timeout), select can block indefinitely. 

RETURN VALUE 

On success select returnsthe number of descriptors contained in the descriptor sets, which may bea ifthetimeout expires 
before anything interesting happens On error, -1 is returned, and errno is set appropriately; the sets and ti meout become 
undefined, so do not rely on their contents after an error. 

ERRORS 

EBADF 
EINTR 
EINVAL 
ENOMEM 

NOTES 

Some code calls select with all three sets empty, n =0, and a non-null timeout; this is a fairly portable way to sleep with 
subsecond precision. 

On Linux, ti meout is modified to reflect the amount of time not slept; most other implementations do not do this This 
causes problems both when Linux codethat readst i meout is ported to other operating systems and when code is ported to 
Linux that reuses a struct timeval for multiple seiectsin a loop without reinitializing it. Consider t i meout to be undefined 
after select returns. 

EXAMPLE 

//include <stdio.h> 

//include <sys/time.h> 

//include <sys/types.h> 

//include <unistd.h> 


An invalid file descriptor was given in one of the sets 
A non-blocked signal was caught, 
n is negative. 

select was unable to allocate memory for internal tables 
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main(void) 


struct timeval tv; 
int retval; 

/* Watch stdin (fd 0) to see when it has input. */ 
FD_ZERO(&rfds); 

FD_SET(0, &rfds); 

/* Wait up to five seconds. */ 



retval = select(1, &rfds, NULL, NULL, &tv); 

/* Don't rely on the value of tv now! */ 

if (retval) 

printf("Data is available now.nn"); 

/* FD_ISSET(0, &rfds) will be true. */ 

else 

printf("No data within five seconds.™"); 

exit(0); 


SEE ALSO 

accept(2), connect(2), read(2), recv(2), send(2), write(2) 


Linux 1.2,11 February 1996 


semctl 

semcti— Semaphore-control operations 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

#include <sys/sem.h> 

DESCRIPTION 

Thefunction performs the control operation specified bycmd on the semaphore set (or on thesumun-nth semaphore of the 
set) identified by se mi d. The first semaphore of the set is indicated by a value of 0 for s emu n. 

Thetypeofarg istheunion 

union semun { 

int val; /* used for SETVAL only */ 

struct semid_ds *buf; /* for IPC_STAT and IPC_SET */ 

ushort ‘array; /* used for GETALL and SETALL */ 


Legal values forcmd are 

ipc_stat C opies info from the semaphore sdt data structure into the structure pointed to by a r g. buf . T he 

argument semnum is ignored. The calling process must have read access privileges on the semaphore set. 
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IPC_SET 


IPC_RMID 

GETALL 

GETNCNT 

GETPID 

GETVAL 

GETZCNT 

SETALL 


SETVAL 


Writes the values of some members of thesemid_ds structure pointed to by a r g .but to the semaphore 
set data structure, updating also its sem_ctime member. Considered members from the user-supplied 
struct semid_ds pointed to by arg.buf are 

sem_perm.uid 

sem_perm.gid 

sem_perm.mode /* only lowest 9-bits */ 

The calling process's effective user ID must be super-user, creator, or owner of the semaphore set. The 
argument semn unis ignored. 

Removes the semaphore set and its data structures immediately, awakening all waiting processes (with 
an error return and errno set to EID RM). The calling process's effective user ID must be super-user, 
creator, or owner of the semaphore set. The argument semnum is ignored. 

Returns semvai for all semaphores of the set into arg .array. The argument semnum is ignored. The 
calling process must have read access privileges on the semaphore set. 

The system call returns the value of semncnt for the semn o-th semaphore of the set (that is, the number 
of processes wai ti ng for an i ncrease of semvai for the s e mn o -th semaphore of the set). T he cal li ng 
processmust have read access privileges on the semaphore set. 

The system call returns the value of sempid for the semn o-th semaphore of the set (that is, the pid of the 
process that executed the last semop call for the semn o-th semaphore of the set). The calling process 
must have read access privileges on the semaphore set. 

The system call returns the value of semvai for the semn o-th semaphore of the set. The calling process 
must have read access privileges on the semaphore set. 

The system call returns the value of semzcnt for the s e mn o - th semaphore of the set (that i s, the number 
of processes wai ting for the semvai of thes emno -th semaphore of the set to become 0). The calling 
processmust have read access privileges on the semaphore set. 

Sets semvai for all semaphores of the set usi ng a r g . array , updati ng also the sem_ctime member of the 
semid_ds structure associated with the set. Undo entries are cleared for altered semaphoresin all 
processes. Processes sleeping on the wait queue are awakened if some semvai becomes 0 or increases. 
The argument semn um is ignored. The calling processmust have alter access privileges on the semaphore 
set. 

sets the value of semvai to a r g. vai for the s e mn u m-th semaphore of the set, updating also the sem_ctime 
member of the semid_ds structure associated to the set. The undo entry is cleared for the altered 
semaphore in all processes. Processes sleeping on the wait queue are awakened if semvai becomes cor 
increases. The calling processmust have alter access privileges on the semaphore set. 


RETURN VALUE 

On fail, the system call returns - 1 , with errno indicating the error. Otherwise the system call returnsa non-negative value, 
depending on cmd, as follows: 

GETNCNT The value of semncnt. 

GETPID The value of sempid. 

GETVAL The value of semvai. 

GETZCNT The value of semzcnt. 


ERRORS 

For a failing return, errno will be set to one of the following values: 
eaccess The calling process hasno access permissions needed to executeemd. 

efault The address pointed to by arg .but or arg .array isn't accessible 

eidrm The semaphore set was removed. 

einval Invalid value for cmd or s emi d. 



eperm The argument cmd has the value ipc_set or ipc_rmid, but the calling process's effective user ID has 

insufficient privileges to execute the command. 

erange The argument cmd hasthe value setall or setval, and the value to which semvai has to be set (for some 

semaphore of the set) is less than 0 or greater than the implementation value semvmx. 

NOTES 

TheiPC_iNFO, sem_stat, and sem_info control calls are used by the ipcs{l) program to provide information on allocated 
resources I n thefuture these can be modified as needed or moved to a proc filesystem interface. 

The following system limit on semaphore sets affects a semcti call: 

semvmx M aximum valuefor semvai; implementation dependent (32767). 

SEE ALSO 

ipc(5), shmget(2), shmat(2), shmdt(2) 

Linux 0.99.13,1 November 1993 


semget 

semget- Gets a semaphore sdt identifier 

SYNOPSIS 

# include <sys/types.h> 

It include <sys/ipc.h> 

# include <sys/sem.h> 

int semget ( key_t key ,int n$ems,int semflg ); 


DESCRIPTION 

This function returns the semaphore set identifier associated with the value of the argument key. A new sdt of nsems 
semaphores is created if key has the value ipc_private or key isn't ipc_private, if no existing message queue is associated to 
key, and if ipc_creat is asserted in semf i g (that is, semfig& ipc_creat isn't 0). The presence in semf i g of the fields ipc_creat 
and ipc_excl plays the same role, with respect to the existence of the semaphore set, as the presence of o_creat and o_excl in 
the mode argument of the open(2) system call—that is, the msgget function fails if semf i g asserts both ipc_creat and ipc_excl 
and asemaphore set already exists for key. 

Upon creation, the lower 9 bits of the argument semf i g define the access permissions (for owner, group, and others) to the 
semaphore sdt in the same format, and with the same meaning, as for the access permissions parameter in theopen(2) or 
creat(2) system call (although theexecute permissions are not used by thesystem, and theterm write permissons, for a 
semaphore sdt, effectively means alter permissions). 

Furthermore while creating, thesystem call initializes the system semaphore sdt data structure semid_ds asfollows 

■ sem_perm. cuid and sem_perm. uid are sdt to the effective user ID of the calling process. 

■ sem_perm.cgid and sem_perm.gid are sdt to the effective group ID of the calling process. 

■ Thelowest-order9 bits of sem_perm. mode are sdt to the lowest-order 9 bits of semf i g. 

■ sem_nsems iSSettOthevalueofnsems. 

■ sem_otime iSSfit to 0. 

■ sem_ctime issdt to the current time. 

The argument nsems can be 0 (a "don't care;') when thesystem call isn't create(2). Otherwise, nsems must be greater than 0 
and less or equal to the maximum number of semaphores per semid (semmsl). 

If the semaphore set already exists, the access permissions are verified, and a check is made to see if it is marked for destruc¬ 
tion. 
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RETURN VALUE 

If successful, the return value will be the semaphore set identifier (a positive integer); otherwise it will be-i, with errno 
indicating the error. 

ERRORS 

For a failing return, errno will be set to one of the following values: 

eacces A semaphore set exists for key, but the calling process has no access permissionsto the set. 

eexist A semaphore set exists for key, and semf i g was asserting both ipc_creat and ipc_excl. 

eidrm The semaphore set is marked to be deleted. 

enoent No semaphore set exists for key, and semfig wasn't asserting ipc_creat. 

enomem A semaphore set has to be created, but the system does not have enough memory for the new data 

structure. 

enospc A semaphore set has to be created, but the system limit for the maximum number of semaphore 

sets (semmni) or the system-wide maximum number of semaphores (semmns) would be exceeded. 

NOTES 

ipc_private isn't a flag field but a key_t type If this special value is used for key, the system call ignores everything but the 
lowest-order 9 bits of s emf i g and creates a new semaphore set (on success). 

The followi ngs are li mits on semaphore set resources affecting a semget cal I : 
semmni System-wide maximum number of semaphore sets; policy dependent. 

semmsl M aximum number of semaphores per semid; implementation dependent (500 currently). 

semmns System-wide maximum number of semaphores; policy dependent. A value greater than 

semmslxsemmni makes it irrelevant. 

BUGS 

Use of ipc_private doesn't inhibit other processes' access to theallocated semaphore set. 

As for the files, there is currently no intrinsic way for a process to ensure exclusive access to a semaphore set. Asserting both 
ipc_creat and ipc_excl in semf i g only ensures (on success) that anew semaphore set will be created; it doesn't imply 
exclusive access to the semaphore set. 

The data structure associated with each semaphore in the set isn’t initialized by the system call. In order to initialize those 
data structures, you have to execute a subsequent call to semcti( 2 ) to perform a setval or a setall command on the 
semaphore set. 

SEE ALSO 

ftok(3), ipc(5), semctl(2), semop(2) 

Linux 0.99.13,1 November 1993 


semop 

semop — Semaphore operations 

SYNOPSIS 

# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/sem.h> 

int semop ( int semid,struct sembuf *sops, unsigned nsops ); 
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DESCRIPTION 

Thefunction performs operations on selected members of the semaphore set indicated by semi d. Each of thensops elements 
in thearray pointed to by sops specifies an operation to be performed on a semaphore by a struct sembuf including the 
following members: 

short sem_num; /* semaphore number: 0 = first */ 
short sem_op; /* semaphore operation */ 
short sem_flg; /* operation flags */ 

Flags recognized in sem_fig are ipc_nowait and semjjndo. If an operation asserts semjjndo, it will be undone when the process 
exits 

The system call semantic assures that the operations will be performed if and only if all of them will succeed. Each operation 
is performed on thesem_num-th semaphore of the semaphore set, where thefirst semaphore of the sdt issemaphoreO and is 
oneof thefollowing three 

■ If sem_op isa positive integer, theoperation addsthis value to semvai. Furthermore if semjjndo isasserted for this 
operation, the system updates the process undo count for this semaphore. Theoperation always goes through, so no 
process sleeping can happen. The calling process must have alter permissionson the semaphore set. 

■ If sem_op iso, the process must have read access permissions on the semaphore set. If semvai is 0, theoperation goes 
through. Otherwise, if ipc_nowait isasserted in sem_fig, the system call fails (undoing all previous actions performed), 
with ermo setto eagain. Otherwise, semzcnt isincremented by 1, and the process sleeps until oneof thefollowing 
occurs 

■ semvai becomes 0 , at which timethe value of semzcnt is decremented. 

■ The semaphore set is removed, causing the system call to fail with errno set to eidrm. 

■ Thecalling process receives a signal that hasto be caught; which causes the value of semzcnt to be decremented and 
the system call to fail with errno set to eintr. 

■ If sem_op is less than 0, the process must have alter permissionson the semaphore set. If semvai is greater than or equal to 
the absolute value of sem_op, the absolute value of sem_op is subtracted by semvai. Furthermore, if semjjndo is asserted for 
this operation, the system updates the process undo count for this semaphore Then theoperation goes through. 
Otherwise if ipc_nowait isasserted in sem_fig, the system call fails (undoing all previous actions performed), with errno 
setto eagain. Otherwise, semncnt isincremented by 1 and the process sleeps until oneof thefollowing occurs: 

■ semvai becomes greater than or equal to the absolute value of sem_op, at which timethe value of semncnt is 
decremented, the absolute value of sem_op is subtracted from semvai and, if semjjndo isasserted for this operation, 
the system updates the process undo count for this semaphore. 

■ The semaphore set is removed from the system: the system call fails, with errno set to eidrm. 

■ Thecalling process receives a signal that hasto be caught; the value of semncnt is decremented, and the system call 
fails with errno SdttO EINTR. 

In case of success, the sempid member of the structure sen for each semaphore specified in thearray pointed to by sops is set 
to the process ID of thecalling process. Furthermore both sem_otime and sem_ctime are set to the current time 

RETURN VALUE 

If successful, the system call returns 0 ; otherwise it returns- 1 , with errno indicating theerror. 

ERRORS 

For a failing return, errno will be set to oneof thefollowing values: 

e 2 big The argument ns ops isgreaterthan semopm, the maximum number of operations allowed per system 

call. 

eacces Thecalling process has no access permissionson the semaphoreset as required by oneof the specified 

operations. 

eagain An operation could not go through, and ipc_nowait was asserted in itssemji g. 

e fault Theaddresspointedtobysops isn't accessible 
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efbig For some operation, the value of sem_num is less than 0 or greater than or equal to the number of 

semaphores in the set. 

eidrm The semaphore set was removed. 

eintr Sleeping on a wait queue, the process received a signal that had to be caught. 

einval The semaphore set doesn't exist, or semi d is less than 0 , or ns ops has a non-positive value. 

enomem The sem_f ig of some operation asserted semjjndo, and the system does not have enough memory to 

allocate the undo structure. 

erange For some operation, semop-hsemvaiis isgreaterthan semvmx, the implementation-dependent maximum 

value for semval. 


NOTES 

The sem_undo structures of a process aren't inherited by its child on execution of atork(2) system call. They are instead 
inherited by the substituting process resulting from the execution oftheexec(2) system call. 

Thefollowing are limits on semaphore set resources affecting a semop call: 

semopm Maximum number of operations allowed for one semop call; policy dependent. 

semvmx M aximum allowable value for semvai; implementation dependent (32767). 

T he implementation has no intrinsic limitsfor theadjust on exit maximum value (semaem), the system-wide maximum 
number of undo structures (semmnu), or the per-process maximum number of undo entries system parameters 

BUGS 

The system maintains a per-process sem_undo structure for each semaphore altered by the process with undo requests Those 
structures are free at process exit. One major cause for unhappiness with the undo mechanism is that it does not fit in with 
the notion of having an atomic set of operations in an array of semaphores The undo requests for an array and each 
semaphore therein might have been accumulated over many semopt calls Should the process sleep when exiting, or should all 
undo operations be applied with the ipc_nowait flag in effect? Currently those undo operations that go through immediately 
are applied, and those that require a wait are ignored silently. Therefore harmless undo usage is guaranteed with private 
semaphores only. 


SEE ALSO 

ipc(5), semctl(2), semget(2) 


Linux 0.99.13,1 November 1993 


send,sendto,sendmsg 

send, sendto, sendmsg— Sends a message from a socket 

SYNOPSIS 

#include <sys/types.h> 

//include <sys/socket.h> 

int sendfint s, const void *msg,int len, unsigned int flags); 
int sendto(int s, const void *m$g, int len, unsigned int flags, 
const struct sockaddr *to, int tolen); 
int sendmsg(int s, const struct msghdr *msg , unsigned int flags); 

DESCRIPTION 

Warning:ThisisaBSD man page As of Linux 0.99.11, sendmsg was not implemented. 

send, sendto, and sendmsg areused to transmit a message to another socket, send may be used only when the socket isin a 
connected state, whereas sendto and sendmsg may be used at any time. 



The address of the target is given by to, with t o i en specifying its size. The length of the message is given by i e n . If the 
message is too long to pass atomically through the underlying protocol, the error emsgsize is returned, and the message is not 
transmitted. 

N o indication of failure to deliver is implicit in a send. Locally detected errors are indicated by a return value of -i. 

If no message space is available at the socket to hold the message to be transmitted, send normally blocks, unless the socket 
has been placed in non-blocking I/O mode. The seiect(2) call may be used to determine when it is possible to send more 
data. 

Thefi ags parameter may indudeoneor moreof thefollowing: 

#define MSG_00B 0x1 /* process out-of-band data */ 

#define MSG_D0NTR0UTE 0x4 /* bypass routing, use direct interface */ 

Thefiag msg_oob is used to send out-of-band data on sockets that support this notion (for example sock_stream); the 
underlying protocol must also support out-of-band data. msg_dontroute is usually used only by diagnostic or routing 
programs. 

See recv(2) for a description of themsghdr structure 

RETURN VALUES 

The call returns the number of characters sent, or-i if an error occurred. 

ERRORS 

EBADF 
ENOTSOCK 
EFAULT 
EMSGSIZE 

EWOULDBLOCK 
ENOBUFS 

ENOBUFS 

HISTORY 

These function calls appeared in BSD 4.2. 

SEE ALSO 

fcntl(2), recv(2), select(2), getsockopt(2), socket(2), write(2) 

BSD Man Paget 24July 1993 


An invalid descriptor was specified. 

The arguments is not a socket. 

An invalid user space address was specified for a parameter. 

The socket requires that message be sent atomically, and the size of the message to be sent made 
thisimpossi ble 

The socket is marked non-blocking, and the requested operation would block. 

Thesystem was unable to allocate an internal buffer. The operation might succeed when buffers 
become available 

Theoutput queuefor a network interface was full. T his generally indicates that theinterface has 
stopped sending, but it might be caused by transient congestion. 


setfsgid 

setfsgid— Sets group identity used for filesystem checks 

SYNOPSIS 

int setfsgid(uid_t fsgid); 

DESCRIPTION 

setfsgid sdts the group ID that the Linux kernel uses to check for all accesses to thefilesystem. Normally, the valueoffsgi d 
will shadow the value of the effective group ID. In fact, whenever the effective group ID is changed, f sgi d will also be 
changed to the new value of the effective group ID. 
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An explicit call to setfsgid is usually only used by programssuch as the Linux N FS server that need to change what group 
ID is used for file access without a corresponding change in the real and effective group IDs. A changein the normal group 
IDsfora program such as the NFS server is a security hole that can expose it to unwanted signals from other group ID s. 
setfsgid will succeed only if the caller is the superuser or if f sgi d matches either the real group ID, effective group ID, saved 
group ID, or the current value of f s g i d. 

RETURN VALUE 

On success, the previous value off sg d is returned. On error, the current value off sgi d isreturned. 

C0NF0RMST0 

setfsgid is Linux specific. 

BUGS 

N o error messages of any kind are returned to the caller. At the very least, eperm should be returned when the call fails. 

SEE ALSO 

setfsuid(2) 

Linux 1.3.15, 6 August 1995 


setfsuid 

setfsuid— Sets user identity used for filesystem checks 

SYNOPSIS 

int setfsuid(uid_t fsuid); 

DESCRIPTION 

setfsuid sets the user ID that the Linux kernel uses to check for all accesses to the filesystem. N ormally, the value of f s ui d 
will shadow the value of the effective user ID. In fact, whenever the effective user ID is changed, fsuid will also be changed 
to the new value of the effective user ID. 

An explicit call to setfsuid is usually used only by programssuch as the Linux N FS server that need to change what user ID 
is used for file access without a corresponding change in the real and effective user IDs A changein the normal user IDsfora 
program such as the NFS server is a security hole that can expose it to unwanted signals from other user ID s. 
setfsuid will succeed only if the caller is the superuser or if f s u i d matches either the real user ID, effective user ID, saved user 
ID, or the current value of f s u i d. 

RETURN VALUE 

On success the previous value of f sui d isreturned. On error, the current value off sui d isreturned. 

C0NF0RMST0 

setfsuid is Linux specific. 

BUGS 

N o error messages of any kind are returned to the caller. At the very least, eperm should be returned when the call fails. 

SEE ALSO 

setfsgid(2) 


Linux 1.3.15, 6 August 1995 



stpgid, getpgid, setpgrp, getpgrp 


setgid 

setgid— Sdtsgroup identity 

SYNOPSIS 

#include <unistd.h> 
int setgid(gid_t gi d); 

DESCRIPTION 

setgid sets the effecti ve group ID of the current process. I f the caller is the superuser, the real and saved group ID s are also 


Under Linux, setgid is implemented like sysv, with saved_ids. This allows a setgid (other than root) program to drop all its 
group privileges, do some unprivileged work, and then re-engage the original effective group ID in a secure manner. 

If the user is root or the program is setgid root, sped al care must be taken. T he setgid function checks the effective gid of 
thecaller and, if it is that of thesuperuser, all process-related group ID s are set to g i d . After this has occurred, it is impossible 
for the program to regain root privileges 

RETURN VALUE 

On success 0 is returned. On error, -1 isreturned, and errno is set appropriately. 

ERRORS 

eperm T he user is not the superuser, and g i d does not match the effective or saved group ID of the calling process 

C0NF0RMST0 

System V 

SEE ALSO 

getgid(2), setregid(2), setegid(2) 

Linux 1.1.36, 29July 1994 


setpgid,getpgid,setpgrp, getpgrp 

setpgid, getpgid, setpgrp, getpgrp— Set^gets process group 

SYNOPSIS 

#include <unistd.h> 

int setpgid(pid_t pid, pid_t pgid); 

pid_t getpgid(pid_t pid); 

int setpgrp(void); 

pid_t getpgrp(void); 

DESCRIPTION 

setpgid sets the process group ID of the process specified by pi d topgid. If pi d is 0 , the process ID of the current process is 
used. If pgi d isO, the process ID of the process specified by pi d is used. 

getpgid returns the process group ID of the process specified by pi d. If pi d is 0, the process ID of the current process is used. 
In theLinuxDLL 4.4.1 library, setpgrp simply calls setpgid(0,0). 
getpgrp is equivalent to getpgid(O). 
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Process groups are used for distribution of signals, and by terminals to arbitrate requests for their input; processes that have 
the same process group as the terminal are foreground and may read, whereas others will block with a signal if they attempt 
to read. 

These callsare thus used by programs such ascsh(l) to create process groups in implementing job control. TheTiocGPGRP 
and tiocspgrp calls described in te™ios(4) are used to get/set the process group of the control terminal. 

RETURN VALUE 

0 n success, setpgid and setpgrp return 0 .0 n error, -1 is returned, and errno is set appropriately, 
getpgid returns a process group on success 0 n error, -1 is returned, and errno isset appropriately, 
getpgrp always returns the current process group. 

ERRORS 

einval pgi d is less than 0 . 

eperm Various permission violations 

esrch p i d does not match any process 

C0NF0RMST0 

Thefunctions setpgid and getpgrp conform to POSIX.1. Thefunction setpgrp isfrom BSD 4.2.1 have no information on 
the source Of getpgid. 

SEE ALSO 

getuid(2), setsid(2), tcsetpgrp(3), termios(4) 

Linux 1.2.4,15 April 1995 


setregid,setegid 

setregid, setegid- Sets real and/or effective group ID 

SYNOPSIS 

#include <unistd.h> 

int setregid(gid_t r gid , gid_t egid ); 

int setegid(gid_t egi d); 

DESCRIPTION 

setregid sets real and effective group IDsof the current process U nprivileged users may changethereal group ID to the 
effective group ID, and vice versa. 

Prior to Linux 1.1.38, the saved ID paradigm, when used with setregid or setegid, was broken. Starting at 1.1.38, it is also 
possi ble to set the effective group ID from the saved user ID. 

0 nly the superuser may make other changes. 

Supplying a value of -1 for either the real or effective group ID forces the system to leave that ID unchanged. 

Currently (Iibc-4.X.X), setegid (egi d) is functionally equivalent to setregid)- 1, egi d ). 

If the real group ID is changed or the effective group ID is set to a value not equal to the previous real group ID, the saved 
group ID will be set to the new effective group ID. 

RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 
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ERRORS 

eperm The current process is not the superuser, and changes other than swapping the effective group ID 

with the real group ID, setti ngone to the value of the other, or setting the effective group ID to the 
valueof the saved group ID wasspecified. 

HISTORY 

Thesetregid function call appeared in BSD 4.2. 

C0NF0RMST0 


SEE ALSO 

getgid(2), setgid(2) 


Linux 1.1.38,2 Augui 1994 


setreuid,seteuid 

setreuid, seteuid- Sets real and / or effective user ID 

SYNOPSIS 

#include <unistd.h> 

int setreuid(uid_t ruid, uid_t euid); 

int seteuid(uid_t eui d ); 

DESCRIPTION 

setreuid sets real and effective user ID s of the current process Unprivileged users may change the real user ID to the 
effective user ID, and vice versa. 

Prior to Linux 1.1.37, the saved ID paradigm, when used with setreuid or seteuid, was broken. 

Starting at 1.1.37, it is also possible to set the effective user ID from the saved user ID. 

0 nly the superuser may make other changes. 

Supplying a value of-i for either the real or effective user ID forces the system to leave that ID unchanged. 

Currently (libc-4.x.x), seteuid (eui d ) isfunctionally equivalent to setreuid )-1 , eui d ). 

If the real user ID is changed or the effective user ID is set to a value not equal to the previous real user ID, the saved user ID 
will be sdt to the new effective user ID. 

RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 

ERRORS 

eperm The current process is not the superuser, and changes other than swapping the effective user ID 

with the real user ID, setti ngone to the value of the other, or setting the effective user ID to the 
valueof the saved user ID wasspecified. 

HISTORY 

The setreuid function call appeared in BSD 4.2. 

C0NF0RMST0 

BSD 4.3 
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SEE ALSO 

getuid(2), setuid(2) 


Linux 1.1.38,2 August 1994 


setsid 

setsid— C reates a session and sets the process group ID 

SYNOPSIS 

#include <unistd.h> 


DESCRIPTION 

setsid () creates a new session if the calling process is not a process group leader. T he calling process is the leader of the new 
session, the process group leader of the new process group, and has no controlling tty. The process group ID and session ID 
of the calling process are set to the PI D of the calling process The calling process will be the only process in this new process 
group and in this new session. 

RETURN VALUE 

It returns the session ID of the calling process. 

ERRORS 

On error, -i will be returned. The only error that can happen is eperm, which is returned when the process group ID of any 
processequalsthePID of the calling process. Thus in particular, setsid fails if the calling process is already a process group 
leader. 

NOTES 

A process group leader is a process with process group I D equal to its PI D. In order to be sure that setsid will succeed, fork, 
and exit, and have the child do setsid)). 

C0NF0RMST0 

POSIX 


SEE ALSO 

setpgid(2), setpgrp(2) 


27 August 1994 


setuid 

setuid— Sets user identity 

SYNOPSIS 

#include <unistd.h> 
int setuid(uid_t ui d); 

DESCRIPTION 

setuid sets the effective user ID of the current process. If the caller isthesuperuser, the real and saved user ID s are also set. 



&mctl 


Under Linux, setuid isimplemented like sysv, with saved_ids. Thisallowsasetuid (other than root) program to drop all its 
user privileges, do some unprivileged work, and then re-engage the original effective user ID in a secure manner. 

If the user is root or the program is setuid root, special care must betaken. The setuid function checks the effective U I D of 
the caller, and, if it is the superuser, all process-related user ID s are set to ui d. After this has occurred, it is impossible for the 
program to regain root privileges 

RETURN VALUE 

On success 0 is returned. On error, -1 is returned, and errno is set appropriately. 

ERRORS 

eperm T he user is not the superuser, and ui d does not match the effective or saved user ID of the calling 

process 

C0NF0RMST0 

System V 

SEE ALSO 

getuid(2), setreuid(2), seteuid(2) 

Linux 1.1.36 29 July 1994 


setup 

setup- Sets up devicesand filesystems mount root filesystem 

SYNOPSIS 

#include <unistd.h> 
syscall0(int, setup); 

DESCRIPTION 

setup iscalled once from within linux/init/main.c. It calls initialization functionsfor devicesand filesystems configured into 
the kernel and then mounts the root filesystem. 

No user process may call setup. Any user process, even a process with superuser permission, will receive eperm. 

RETURN VALUE 

setup always returns -1 for a user process 

ERRORS 

eperm Always, for a user process 

C0NF0RMST0 

Thisfunction is Linux specific. 

Linux 1.2.9,3 May 1996 


shmctl 

shmcti — Shared memory control 
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SYNOPSIS 

//include <sys/ipc.h> 

#include <sys/shm.h> 

int shmctl(int s hmi d,int cmd, struct shmid ds *buf); 

DESCRIPTION 

shmctio allows the user to receive information on ashared memory segment, settheowner, group, and permissions of a 
shared memory segment, or destroy a segment. The information about the segment identified by s hmi d is returned in a 
s h mi d _ d s structure: 
struct shmid_ds { 

struct ipc_perm shm_perm; /* operation perms */ 
int shm_segsz; /* size of segment (bytes) */ 
time_t shm_atime; /* last attach time */ 
time_t shm_dtime; /* last detach time */ 
time_t shm_ctime; /* last change time */ 
unsigned short shm_cpid; /* pid of creator */ 
unsigned short shm_lpid; /* pid of last operator */ 
short shm_nattch; /* no. of current attaches */ 

/* the following are private */ 

unsigned short shm_npages; /* size of segment (pages) */ 
unsigned long *shm_pages; 

struct shm_desc 'attaches; /* descriptors for attaches */ 

Thefields in the member shm_ perm can beset: 
struct ipc_perm 
key_t key; 

ushort uid;/‘owner euid and egid */ 

ushort mode; /* lower 9 bits of access modes */ 
ushort seq; /* sequence number */ 


Thefollowing c md s are available: 

ipc_stat Used to copy the information about the shared memory segment into the buffer, but . The user 

must have read access to the shared memory segment. 

ipc_set U sed to apply the changes the user has made to the u i d, g i d , or mo d e members of the s h m. p e r ms 

field. Only the lowest 9 bits of mode are used. Theshm.cti me member is also updated. The user 
must be the owner, the creator, or the superuser. 

ipc_rmid Used to mark the segment asdestroyed. It will actually be destroyed after the last detach. (That is, 

when thes hm_ nat t c h member of the associated structures hmi d.ds iszero.)Theuser must be the 
owner, the creator, or the superuser. 

The user must ensure that a segment is eventually destroyed; otherwise the pages that were faulted in will remain in memory 

or swap. 

In addition, the superuser can prevent or allow swapping of ashared memory segment with the following cmds (Linux only) 

shm_lock Prevents swapping of ashared memory segment. The user must fault in any pages that are required 

to be present after locking is enabled. 

shmjjnlock Allows the shared memory segment to be swapped out. 

TheiPC_iNFO, shm_stat, and shm_info control calls are used by theipcs(l) program to provide information on allocated 

resources In the future, these may be modified as needed or moved to a proc filesystem interface. 
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SYSTEM CALLS 

fork () After a fork(), the child inherits the attached shared memory segments 

execo After an execo, all attached shared memory segments are detached (not destroyed). 

exit o 0 n exit (), all attached shared memory segments are detached (not destroyed). 

RETURN VALUE 

0 is returned on success; -i on error. 

ERRORS 

On error, errno will be set to one of thefollowing: 

eaccess Returned if ipc_stat is requested and shm_perm. modes does not allow read access for msqid. 

efault T he argument cmd hasthe value ipc_set or ipc_stat, but the address pointed to by buf isn't 

accessible 

einval Returned if shmid is not a valid identifier, or cmd is not a valid command. 

eidrm Returned if shmid pointsto a removed identifier. 

eperm Returned if ipc_set or ipc_rmid is attempted, if the user is not the creator, the owner, or the 

superuser, and if the user does not have permission granted to his group or to the world. 

SEE ALSO 

shmget(2), shmop(2) 

Linux 0.99.11, 28 N ovember 1993 


shmget 

shmget- Allocates a shared memory segment 

SYNOPSIS 

#include <sys/ipc.h> 

#include <sys/shm.h> 

int shmget(key_t key, int size, int s h mf i g); 

DESCRIPTION 

shmget o returns the identifier of the shared memory segment associated with the value of the argument key. A new shared 
memory segment, with its size equal to the rounding up of si ze to a multiple of page_size, is created if key hasthe value 
ipc_private or if key isn't ipc_private, if no shared memory segment is associated to key, and if ipc_creat is asserted in 
shmtig (that is, shmfig& ipc_creat isn't 0). The presence in shmfig iscomposed of 

ipc_creat C reates a new segment. If this flag is not used, shmget o will find the segment associated with key, 

check to see if the user has permission to receive the shmid associated with the segment, and ensure 
the segment is not marked for destruction. 
ipc_excl U sed with ipc_creat to ensure failure if the segment exists 

mode_fiags (lowest 9 bits) Specifiesthe permissions granted to the owner, group, and world. Presently, the 

execute permissionsare not used by the system. 

If a new segment is created, the access permissionsfrom shmfig are copied into the shm_perm member of the shmid_ds 
structure that defines the segment. Following istheshmid_ds structure: 

struct ipc_perm shm_perm; /* operation perms */ 
int shm_segsz; /* size of segment (bytes) */ 




key_t key; 


ushort uid; /* owner euid and egid */ 
ushort gid; 

ushort cuid; /* creator euid and egid */ 
ushort egid; 



Furthermore while creating, the system call initializes the system shared memory segment data structure shmid_ds as follows: 

■ shm_perm.cuid and shm_perm. uid aresdt to the effective user ID of the calling process. 

■ shm_perm.cgid and shra_pera. 0 id aresdt to the effective group ID of the calling process. 

■ Thelowest-order9 bits of shm_perm. mode are sdt to the lowest-order 9 bit of shmfig. 

■ shm_segsz issfitto thevalueofsi ze. 

■ shm_lpid, shm_nattch, shm_atime, and shm_dtime are Set to 0 . 

■ shm_ctime issdt to the current time. 

If the shared memory segment already exists, the access permissions are verified, and a check is made to see if it is marked for 
destruction. 


After a fork(), the child inherits the attached shared memory segments 
After an execo, all attached shared memory segments are detached (not destroyed). 

0 n exit (), all attached shared memory segments are detached (not destroyed). 

RETURN VALUE 

A valid segment identifier, shmid, is returned on success -i on error. 

ERRORS 

On failure, errno is set to one of the following: 

einval Returned if shmmin is greater than s i z e , if s i z e is greater than shmmax, or if s i z e isgreater than the 

size of the segment. 

eexist Returned if ipc_creat \ ipc_excl was specified and the segment exists. 

eidrm Returned if the segment is marked as destroyed or was removed. 

enospc Returned if all possible shared memory ID shave been taken (shmmni) or if allocating a segment of 

the requested size would cause the system to exceed the system-wide limit on shared memory 
(shmall). 

enoent Returned if no segment exists for thegiven key , and ipc_creat was not specified. 

eacces Returned if the user does not have permission to access the shared memory segment. 

enomem Returned if no memory could be allocated for segment overhead. 


SYSTEM CALLS 
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NOTES 

ipc_private isn't a flag field butakey_t type If this special value is used for key, the system call ignores everything but the 
lowest order 9 bits of s h mf i g and creates a new shared memory segment (on success). 

Thefollowing are limits on shared memory segment resources affecting a shmget call: 
shmall System-wide maximum of shared memory pages: policy dependent. 

shmmax M aximum size in bytes, for a shared memory segment; implementation dependent (currently 

4MB). 

shmmin M ini mum size in bytes, for a shared memory segment; implementation dependent (currently 1 

byte although page_size isthe effective minimum size). 

shmmni System-wide maximum number of shared memory segments; implementation dependent (currently 

4096). 

The implementation has no specific limits for the per-process maximum number of shared memory segments (shmseg). 

BUGS 

U se of ipc_private does not inhibit other processes' access to the allocated shared memory segment. 

As for the files, there is currently no intrinsic way for a process to ensure exclusive access to a shared memory segment. 
Asserting both ipc_creat and ipc_excl in shmf i g only ensures (on success) that a new shared memory segment will be 
created; it doesn't imply exclusive access to the segment. 

SEE ALSO 

ftok(3), ipc(5), shmctl(2), shmat(2), shmdt(2) 

Linux0.99.11, 28 November 1993 


shmop 

shmop- Shared memory operations 

SYNOPSIS 

#include <sys/types.h> 

//include <sys/ipc.h> 

//include <sys/shm.h> 

char *shmat ( int s hmi d, char *sh mailt., int shmflg ); 
int shmdt ( char *s h ma ddr ); 


DESCRIPTION 

The function shmat attaches the shared memory segment identified by shmid to the data segment of the calling process. The 
attaching address is specified by shmaddr with one of the following criteria: 

■ If shmaddr iso, the system tries to find an unmapped region in the range 1-1.5GB, starting from the upper value and 
coming down from there 

■ If shmaddr isn't 0 and shm_rnd is asserted in shmfig, the attach occurs at the address equal to the rounding down of 
shmaddr to a multiple of shmlba. 0 therwise, shmaddr must be a page-aligned address at which theattach occurs. 

If shm rdonly is asserted in shmf i g, the segment isattached for reading, and the process must have read access permissions to 
the segment. Otherwise the segment isattached for read and write, and the process must have read and write access 
permissions to the segment. There is no notion of a write-only shared memory segment. 

T he brk value of the calling process is not altered by the attach .The segment will automatically be detached at process exit. 
T he same segment may be attached as a read and as a read-write segment, more than once in the process's address space. 
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On asuccessful shmat call, the system updates the members of the structure shmid_ds associated to the shared memory 
segment asfollows 

■ shm_atime issdt to the current time. 

■ shm_ipid is set to the process ID of the calling process 

■ shm_nattch is incremented by 1. 

N otethat the attachment will also succeed if the shared memory segment is marked to be deleted. 

The function shmdt detaches from the calling process's data segment the shared memory segment located at the address 
specified by shmaddr. The detaching shared memory segment must be one among the currently attached ones (to the 
process's address space) with shmaddr equal to the value returned by its attaching shat call. 

On asuccessful shmdt call, the system updates the members of the structure shmtd_ds associated to the shared memory 
segment asfollows 

■ shm_dtime issdt to the current time. 

■ shm_iptd is set to the process ID of the calling process 

■ shm_nattch is decremented by 1. If it becomes 0 and the segment is marked for deletion, the segment is deleted. 

The occupied region in the user space of the calling process is unmapped. 

SYSTEM CALLS 

fork () After a fork(), the child inherits the attached shared memory segments 

execo After an execo, all attached shared memory segments are detached (not destroyed), 

exit () 0 n exit () , all attached shared memory segments are detached (not destroyed). 

RETURN VALUE 

On a failure, both functions return -i with errno indicating the error; otherwise, shmat returns the address of the attached 
shared memory segment, and shmdt returns®. 

ERRORS 

When shmat fails at return errno will be set to one of the following values: 
eacces The calling processhasno access permissions for the requested attach type 

einval Invalid shmi d value, unaligned (that is, not page-aligned and shm_rnd was not specified) or invalid 

shmaddr value, or failing attach at brk. 

enomem Could not allocate memory for the descriptor or for the page tables 

The function shmdt can fail only if there is no shared memory segment attached at shmaddr ; in such a case errno will besdtto 
einval at rdturn. 

NOTES 

On executing a tork(2) system call, the child inherits all the attached shared memory segments 

The shared memory segments attached to a process executing anexec(2) system call will not be attached to the resulting 

process 

Thefollowing isa system parameter affecting a shmat system call: 

shmlba Segments low-boundary address multiple. M ust be page aligned. For the current implementation, 

the shmbla value is page_size. 

T he implementation has no intrinsic limit to the per-process maximum number of shared memory segments (shmseg) 

SEE ALSO 

ipc(5), shmctl(2), shmget(2) 


Linux 0.99.13, 28 November 1993 



sigaction, sigprocmask, sigpending, sgsuspend 


shutdown 

shutdown— Shuts down part of a full-duplex connection 

SYNOPSIS 

#include <sys/socket.h> 
int shutdown(int s ,int how); 

DESCRIPTION 

The shutdown call causes all or part of a full-duplex connection on the socket associated with $ to be shut down. If how iso, 
further receives will be disallowed. If how is i, further sends will be disallowed. If how is2, further sends and receives will be 
disallowed. 

RETURN VALUE 

On success, o is returned. On error, -i isreturned, and errno is set appropriately. 

ERRORS 

ebadf s is not a valid descriptor. 

enotsock s is a fi le, not a socket. 

enotconn The specified socket is not connected. 

HISTORY 

The shutdown function call appeared in BSD 4.2. 

SEE ALSO 

connect(2), socket(2) 

BSD Man Page 24July 1993 

sigaction,sigprocmask,sigpending, sigsuspend 

sigaction, sigprocmask, sigpending, sigsuspend—PO SIX Signal-handling functions. 

SYNOPSIS 

#include <signal.h> 

int sigaction(int signum , const struct sigaction ‘act, struct sigaction ‘oldact); 
int sigprocmask(int how, const sigset_t ‘set, sigset_t * oIdset ); 
int sigpending(sigset_t ‘set); 
int sigsuspend(const sigset_t ‘mask); 

DESCRIPTION 

The sigaction system call is used to change the action taken by a process on receipt of a specific signal, 
si gnum specifies the signal and can beany valid signal except sigkill and sigstop. 

If act is non-null, the new action for signal signum is installed from act . If oi dact is non-null, the previous action is saved in 

The sigaction structure isdefined as 
struct sigaction { 

void (*sa_handler)(int); 
sigset_t sajnask; 
int sa_flags; 
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} 

sa_handier specifies the action to be associated with si gnum and can be sig_dfl for the default action, sig_ign to ignore this 
signal, or a pointer to a signal-handling function. 

sajnask gives a mask of signals that should deblocked during execution of the signal handler. In addition, thesignal that 
triggered the handler will be blocked unless the sa_nodefer or sa_nomask flag is used. 

sa_f lags specifies a set of flags that modify the behavior of the signal-handling process. It isformed by the bitwise 0 R of zero 
or more of the following: 

sa_nocldstop If si gnum issiGCHLD, do not receive notification when child processes stop (that is, when 

child processes receive one of sigstop, sigtstp, sigttin, orsiGrrou). 
sa_oneshot or sa_resethand Restores the signal action to the default state once the signal handler has been called. 

(This is the default behavior of thesignai(2) system call.) 

sa_restart Provides behavior compatible with BSD signal semantics by making certain system calls 

restartable across signals 

sa_nomask or sa_nodefer D oes not prevent the signal from being received from within its own signal handler. 

The sa_restorer element is obsolete and should not be used. 

Thesigprocmask call isused to change the list of currently blocked signals. The behavior of the cal I is dependent on the value 
of ho», asfollows 

sig_block The set of blocked signals is the union of the current set and the set argument. 

sigjjnblock The signals in set are removed from the current set of blocked signals. It is legal to 

attempt to unblock a signal that isnot blocked. 
sig_setmask Thesetof blocked signals is set to the argument set. 

If o i dset is non-null, the pre/ious value of thesignal mask is stored in oi dset. 

Thesigpending call allows the examination of pending signals (those that have been raised while blocked). Thesignal mask 
of pending signals is stored in set. 

Thesigsuspend call temporarily replaces the signal mask for the process with that given by mask and then suspends the 
process until a signal is received. 

RETURN VALUES 

sigaction, sigprocmask, slgpending, and sigsuspend return 0 On SUCCeSS and -1 On error. 

ERRORS 

einval An invalid signal was specified. This will also be generated if an attempt is made to 

change the action for sigkill or sigstop, which cannot be caught. 
efault act, oi dact, set, oral dset points to memory that isnot a valid part of the process 

address space 

eintr System call was interrupted. 

NOTES 

It isnot possibleto block sigkill or sigstop with the sigprocmask call. Attempts to do so will be silently ignored. 

Setting sigchld to sig_ign provides automatic reaping of child processes. 

T he PO SI X spec only defi nes sa_nocldstop. U se of other sa flags is non- portable. 

The sa_resethand flag i s compatible with the SV R4 flag of the same name. 
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ThesA_NODEFER flag iscompatiblewith the SVR4 flag of the same name under kernels 1.3.9 and newer. 0 n older kernels, the 
Linux implementation will allow the receipt of any signal, not just the one you are installing (effectively overriding any 
sajnask settings). 

ThesA_RESETHAND and sa_nodefer namesfor SVR4 compatibility are present only in library versions 3.0.9 and greater, 
sigaction can be called with a null second argument to query the current signal handler. It can also be used to check whether 
a given signal is valid for the current machine by calling it with null second and third arguments. 

See sigsetops(3) for details on manipulating signal sets. 

C0NF0RMST0 

POSIX, SVR4 

SEE ALSO 

kill(l), kill(2), killpg(2), pause(2), raise(3), siginterrupt(3), signal(2), signal(7), sigse-tops(3), sigvec(2) 

Linux 1.3,24 August 1995 


signal 

signal- AN SI C signal handling 

SYNOPSIS 

#include <signal.h> 

void (*signal(int signum.void (*handler )(int)))(int); 

DESCRIPTION 

The signal system call installs a new signal handler for the signal with number si gnu m. The signal handler is set to handi er, 

which can be a user-specified function or one of the following: 

sig_ign Ignores the signal. 

sig_dfl Resets the signal to its default behavior. 

The integer argument that is handed over to the signal-handling routine is the signal number. This makes it possible to use 
one signal handler for several signals 

RETURN VALUE 

signal returns the previous value of the signal handler, or sig_err on error. 

NOTES 

Signal handlers cannot beset for sigkill or sigstop. 

U nlike on BSD systems signals under Linux are reset to their default behavior when raised. H owever, if you include <bsd/ 
signal.h> instead of <signai.h>, signal is redefined as_bsd_signai, and signal has the BSD semantics Both versions of 
signal are library routines built on top of sigaction(2). 

If you're confused by the prototype at the top of this man page, it may help to see it separated out like this: 

typedef void (*sighandler_t)(int); 

sighandler_t signal(int signum, sighandler_t handler); 

According to PO SIX, the behavior of a process isundefined after it ignores a sigfpe, sigill, or sigsegv signal that was not 
generated by the kino or raised function. Integer division by 0 has undefined result. On some architectures it will 
generate a sigfpe signal. Ignoring this signal might lead to an endless loop. 
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CONFORMSTO 

ANSI C 

SEE ALSO 

kill(l), kill(2), killpg(2), pause(2), raise(3), sigaction(2), signal(7), sigsetops(3), sigvec(2), alarm(2) 

Linux2.0, 21 July 1996 


sigblock,siggetmask,sigsetmask,sigmask 

sigblock, siggetmask, sigsetmask, sigmask— M anipulate the Signal mask 

SYNOPSIS 

#include <signal.h> 
int sigblock(int mask); 
int siggetmask(void); 
int sigsetmask(int mask); 
int sigmask(int si gnum); 


DESCRIPTION 

This interface is made obsolete by sigprocmask(2). 

The sigblock system call adds the signals specified in mask to the set of signals currently being blocked from delivery. 

The sigsetmask system call replaces the set of blocked signalstotally with a new set specified in mask. Signals are blocked if 
the corresponding bit in mask isal. 

The current set of blocked signals can be obtained using siggetmask. 

The sigmask macro is provided to construct the mask for a given s i g num. 

RETURN VALUES 

siggetmask returns the current set of masked signals, 
sigsetmask and sigblock return the previous set of masked signals 

NOTES 

Prototypes for these functions are only available if _use_bsd isdefined before <signai.h> is included. 

It isnot possibleto block sigkill or sigstop— this restriction is silently imposed bythesystem. 

HISTORY 

These function callsappeared in BSD 4.3 and are deprecated. 

SEE ALSO 

kill(2), sigprocmask(2), signal(7) 

Linux 1.3,31 August 1995 


sigpause 

sigpause— Atomically releases blocked signals and waits for interrupt 



SYNOPSIS 

#include <signal.h> 
int sigpause(int sigmask); 

DESCRIPTION 

This interface is made obsolete by sigsuspend(2). 

sigpause assigns s i g ma s k to thesdt of masked signals and then waits for a signal to arrive; on return, the set of masked signals 
is restored. 

sigmask is usually 0 to indicate that no signals are to be blocked, sigpause always terminates by being interrupted, returning 
-1 with errno S6tt0 EINTR. 

HISTORY 

The sigpause function call appeared in BSD 4.3 and isdeprecated. 

SEE ALSO 

sigsuspend(2), kill(2), sigaction(2), sigprocmask(2), sigblock(2), sigvec(2) 

Linux 1.3, 24July 1993 


sigreturn 

sigreturn— Returns from the signal handler and cleans up the stack frame 

SYNOPSIS 

int sigreturnfunsigned long _unused); 

DESCRIPTION 

When the Linux kernel creates the stack frame for a signal handler, a call to sigreturn isinserted into the stack frame so that 
thesignal handler will call sigreturn upon return. This inserted call to sigreturn cleans up the stack so that the process can 
restart from where it was interrupted by the signal. 

RETURN VALUE 

sigreturn never returns 

WARNING 

The sigreturn call isused by the kernel to implement signal handlers. It should never be called directly. Better yet, the 
specific use of the unused argument varies depending on the architecture. 

C0NF0RMST0 

sigreturn isspecificto Linux. 

FILES 

/usr/src/linux/arch/i386/kernel/signal.c 
/usr/src/linux/arch/alpha/kernel/entry.S 


SEE ALSO 

kill(2), signal(2), signal(7) 


Linux 1.3.20,21 August 1995 
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sigvec— BSD software signal facilities 

SYNOPSIS 

#include <bsd/signal.h> 

int sigvec(int sig, struct sigvec **ec, struct sigvec *ovec); 

DESCRIPTION 

This interface is made obsolete by sigaction(2). 

Under Linux, sigvec is#detined to sigaction, and provides at best a rough approximation of the BSD sigvec interface. 

SEE ALSO 

sigaction(2), signal(2) 

Linux 1.3 31 Auguil995 

socket 

socket— C reates an endpoint for communication 

SYNOPSIS 



DESCRIPTION 

socket creates an endpoint for communication and returns a descriptor. 

Thedomai n parameter specifiesa communications domain within which communication will take place; thisselects the 
protocol family that should be used. These families are defined in the include file sys/socket.h.Thecurrently understood 
formats are 

UN IX internal protocols 
ARPA Internet protocols 
ISO protocols 

Xerox N dtwork Systems protocols 
IM P host at IM P link layer 

The socket has the indicated type, which specifies the semantics of communication. The currently defined types are 

SOCK_STREAM 

SOCK_DGRAM 

S0CK_RAW 

SOCK_SEQPACKET 

S0CK_RDM 

A sock_stream type provides sequenced, reliable two-way connection-based byte streams An out-of-band data transmission 
mechanism may be supported. A sock_dgram socket supports datagrams (connectionless unreliable messages of a fixed, 
typically small, maximum length). A sock_seqpacket socket may provide a sequenced, reliable, two-way connection-based 
data transmission path for datagrams of fixed maximum length; a consumer might be required to read an entire packet with 
each read system call. This facility is protocol specific, and presently isimplemented only for pf_ns. sock_raw sockets provide 
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access to internal network protocols and interfaces. The types sock_raw, which is available only to the superuser, and 
sock_rdm, which isplanned but not yet implemented, are not described here. 

T he p r o t o c o i specifies a particular protocol to be used with the socket. N ormally only a si ngle protocol exists to support a 
particular socket type within a given protocol family. However, it is possiblethat many protocols may exist, in which case a 
particular protocol must be specified in this manner. The protocol number to use is particular to the communication domain 
in which communication isto take place; see protocois(5). 

Sockets of type sock_stream are full-duplex byte streams, similar to pipes. A stream socket must be in a connected state before 
any data can be sent or received on it. A connection to another socket is created with a connect(2) call. Once connected, data 
may be transferred using read(2) and write(2) callsor some variant of thesend(2) and recv(2) calls. When a session has been 
completed, a ciose(2) may be performed. Out-of-band data can also be transmitted as described in send(2) and received as 
described in recv(2). 

The communications protocols used to implement a sock_stream ensure that data is not lost or duplicated. If a piece of data 
for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time the 
connection isconsidered broken, and calls will indicate an error with -i returnsand with etimedout as thespecific codein the 
global variable errno. The protocols optionally keep sockets warm by forcing transmissions roughly every minute in the 
absence of other activity. An error isthen indicated if no response can be elicited on an otherwise idle connection for a 
extended period (for example, 5 minutes). A sigpipe signal is raised if a process sends on a broken stream; this causes naive 
processes, which do not handle the signal, to exit. 

sock_seqpacket sockets employ the same system calls as sock_stream sockets The only difference is that read(2) calls will 
return only the amount of data requested, and any that is remaining in the arriving packet will be discarded. 
sock_dgram and sock_raw sockets allow the sending of datagrams to correspondents named in send(2) calls. D atagrams are 
generally received with recvfrom(2), which returns the next datagram with its return address. 

An fcnti(2) call can be used to specify a process group to receive a sigurg signal when the out-of-band data arrives. It can 
also enable non-blocking I/O and asynchronous notification of I/O events via sigio. 

The operation of sockets is controlled by socket-level options These options are defined in thefile sys/socket .h. 
setsockopt(2) and getsockopt(2) and are used to set and get options respectively. 

RETURN VALUES 

A -i is returned if an error occurs; otherwise, the return value is a descriptor referencing the socket. 

ERRORS 

EPR0T0N0SUPP0RT 
EMFILE 
ENFILE 
EACCESS 
ENOBUFS 

HISTORY 

The socket function call appeared in BSD 4.2. 

SEE ALSO 

accept(2), bind(2), connect(2), getprotoent(3), getsockname(2), getsockopt(2), ioctl(2), listen(2), read(2), recv(2), 
select(2), send(2), shutdown(2), socketpair(2), write(2) 

"An Introductory 4.3 BSD Interprocess Communication T utorial" is reprinted in UN IX Programmer's Supplementary 
DocumentsVolumel 

"BSD Interprocess Communication T utorial" is reprinted in U NIX Programmer's Supplementary DocumentsVolumel 

BSD Man Page 24July 1993 


The protocol type or the specified protocol is not supported within thisdomain. 

The per-process descriptor table isfull. 

The system file table isfull. 

Permission to create a socket of the specified type and/or protocol is denied. 

I nsufficient buffer space is available. T he socket cannot be created until sufficient resources are 
freed. 
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socketcall 

socketcaii— Socket system calls 

SYNOPSIS 

int socketcall(int call , unsigned long *a r g s ); 

DESCRIPTION 

socketcaii isa common kernel entry point for the socket system calls call determines which socket function to invoke, a r gs 
points to a block containing the actual arguments, which are passed through to the appropriate call. 

User programs should call the appropriate functions by their usual names. 0 nly standard library implementors and kernel 
hackers need to know about socketcaii. 

SEE ALSO 

accept(2), bind(2), connect(2), getpeername(2), getsockname(2), getsockopt(2), listen(2), recv(2), recvfrom(2), send(2), 
sendto(2), setsockopt(2), shutdown(2), socket(2), socketpair(2) 

Linux 1.2.4,15 April 1995 


socketpair 

socketpair— C reates a pair of connected sockets 

SYNOPSIS 

#include <sys/types.h> 

//include <sys/socket.h> 

int socketpair(int d, int type, int protocol , int sv[2]); 

DESCRIPTION 

The call creates an unnamed pair of connected sockets in the specified domain d , of the specified type, and using the 
optionally specified protocol .The descriptors used in referencing the new sockets are returned in sv [ 0 ] and sv [i ]. The two 
sockets are indistinguishable. 

RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 

ERRORS 

EMFILE 

EAFNOSUPPORT 
EPROTONOSUPPORT 
EOPNOSUPPORT 
EFAULT 

HISTORY 

The socketpair function call appeared in BSD 4.2. 

BUGS 

Thiscall is currently implemented only for theUN IX domain. 


Too many descriptors are in use by this process 

The specified address family is not supported on this machine 

The specified protocol is not supported on this machine 

The specified protocol does not support creation of socket pairs 

The address s» does not specify a valid part of the process's address space 
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SEE ALSO 

read(2), write(2), pipe(2) 


BSD Man Page 24July 1993 


stat, f stat, lstat 

stat, fstat, lstat— Get file status 

SYNOPSIS 

#include <sys/stat.h> 

#include <unistd.h> 

int statfconst char *f i I e_ n a me,struct stat *buf); 

int fstat(int f i I edes,struct stat *buf); 

int lstat(const char *f i I e_ n a me, struct stat *buf ); 


DESCRIPTION 

These functions return information about the specified file. You do not need any access rights to the file to get this 
information, but you need search rights to all directories named in the path leading to the file, 
stat statsthefilepointed to by f i i e.name andfillsin but. 

istat is identical to stat, except that the link itself is stated, not thefile that isobtained by tracing the links, 
fstat is identical to stat, except that the open file pointed to by f i i edes (as returned by open(2)) isstated in place of 

They all return a stat structure, which is declared as follows; 


struct stat 





of f_t 

unsigned long 
unsigned long 




/* device */ 

/•protection */ 

/* number of hard links */ 

/* group ID of owner */ 

/* device type (if inode device) */ 
/* total size, in bytes */ 

/* blocksize for filesystem I/O */ 
/* number of blocks allocated */ 

/* time of last access */ 

/* time of last modification */ 

/* time of last change */ 


N ote that s t . b i o c k s may not always be in terms of blocks of size s t . bi k s i z e , and that s t _ b i k s i z e may instead provide a 
notion of the "preferred" block size for efficient filesystem I/O. 

Not all the Linux filesystems implement all the time fields Traditionally, st_ at i me ischanged by mknod(2), utime(2), read(2), 
write(2), and truncate(2). 

Traditionally, s t _ mt i me ischanged by mknod(2), utime(2), and write(2). st_mti me is not changed for changes in owner, group, 
hard link count, or mode. 

Traditionally, st _cti me ischanged by writing or by setting inode information (that is, owner, group, link count, mode, and 
so on). 
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Thefollowing macros are defined to check the file type: 
s_iSLNK(m) Is it a symbolic link? 

s_iSREG(m) Is it a regular file? 

s_isdir( m ) Is it a directory? 

s_iscHR(m) Is it a character device? 

s_iSBLK(m) Is it a block device? 

S_ISFIF0(m) IsitfifO? 

S_ISS0CK(m) Is it a socket? 


Thefollowing flags are defined forthest_mode field: 


S_IFMT 

S_IFS0CK 

S_IFLNK 

S_IFREG 

S_IFBLK 

S_IFDIR 

S_IFCHR 

S_IFIF0 

S_ISUID 

S_ISGID 

S_ISVTX 

S_IRWXU 

S_IRUSR (S_IREAD) 
S_IWUSR (s_iwrite) 

S_IXUSR (S_I EXEC) 

S_IRWXG 

S_IRGRP 

S_IWGRP 

S_IXGRP 

S_IRWX0 

S_IR0TH 

S_IW0TH 

S_IX0TH 


00170000 Bitmask for the file type bitfields 

0140000 Socket 

0120000 Symbolic link 

0100000 Regular file 

0060000 Block device 

0040000 D i rectory 

0020000 Character device 

0010000 Fifo 

0004000 SetUID bit 

0002000 SetGID bit 

0001000 Sticky bit 

00700 User (file owner) has read, write, and execute permission 

00400 User has read permission 

00200 U ser has write permission 

00100 User has execute permission 

00070 G roup has read, write, and execute permission 

00040 Group has read permission 

00020 Group has write permission 

00010 G roup has execute permission 

00007 others have read, write, and execute permission 

00004 Others have read permission 

00002 Others have write permission 

00001 Others have execute permission 


RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 


ERRORS 

EBADF f i I edes isbad. 

enoent Filedoes not exist. 


C0NF0RMST0 

SVID (not istato), AT&T (not istato), POSIX (not istato), X/O PEN (not istato), BSD 4.3 

SEE ALSO 

chmod{2), chown(2), readlink(2), utime(2) 


Linux 1.1.75,1 January 1995 
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statfs,fstatfs 

statfs, fstatfs- Gdt filesystem statistics 

SYNOPSIS 

#include <sys/vfs.h> 

int statfs(const char *pat h, struct statfs *buf); 
int fstatfs(int fd, struct statfs *buf); 


DESCRIPTION 

statfs returns information about a mounted filesystem, path is the pathname of any file within the mounted filesystem, but 
is a pointer to a statf s structure defined as follows: 


f_blocks; 

f_bfree; 


/* type of filesystem (see below) */ 

/* optimal transfer block size */ 

/* total data blocks in filesystem */ 

/* free blocks in fs */ 

/* free blocks avail to non-superuser */ 
/* total file nodes in filesystem */ 

/* free file nodes in fs */ 

/* filesystem id */ 

/* maximum length of filenames */ 

/* spare for later */ 


Filesystem types: 


linux/ext2_fs.h: 
linux/ext2_fs.h: 
linux/ext_fs.h: 
linux/isojfs.h: 
linux/minix_fs.h 
linux/minix_fs.h 
linux/minix_fs.h 
linux/msdos_fs.h 
linux/nfs_fs.h: 
linux/proc_fs.h: 


EXT2_0 LD_SUP ER_MAGIC 

EXT2_SUPER_MAGIC 

EXT_SUPER_MAGIC 

ISOFS_SUPER_MAGIC 

MINIX_SUPER_MAGIC 

MINIX_SUPER_MAGIC2 

N EW_MINIX_SU P E R_MAGIC 

MSDOS_SUPER_MAGIC 

NFS_SUPER_MAGIC 

PROC_SUPER_MAGIC 

XIAFS_SUPER_MAGIC 


0XEF51 

0XEF53 

0x137D 

0X9660 

0x137F /* 

0x138F /* 

0x2468 /* 

0x4d44 

0x6969 

0x9fa0 

0X012FD16D 


orig. minix */ 

30 char minix */ 
minix V2 */ 


Fields that are undefined for a particular filesystem are set to -i. fstatfs returnsthesame information about an open file 
referenced by descriptor f d. 


RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 


ERRORS 

For statfs: 

ENOTDIR 

EINVAL 

ENAMETOOLONG 

ENOENT 

EACCES 

ELOOP 


A component of the path prefix of path is not a directory, 
path contains a character with the high-order bit set. 

The length of a component of path exceeds 255 characters, or the length of path exceedsl,023 
characters. 

Thefile referred to bypath does not exist. 

Search permission is denied for a component of the path prefix of pat h. 

T 00 many symbolic links were encountered in translating pat h. 
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EFAULT 
EIO 

For fstatfs: 

EBADF 
EFAULT 
EIO 

SEE ALSO 

stat(2) 

stime 

stime— Set time 

SYNOPSIS 

#include <time.h> 

DESCRIPTION 

stime sets the system's idea of the time and date, time, pointed to byt, is measured in seconds from 00:00:00 GM T January 
1,1970. stimeo may only be executed by the superuser. 

RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 

ERRORS 

eperm Thecaller is not the superuser. 

C0NF0RMST0 

SVID, AT&T, X/O PEN 

SEE ALSO 

date(l) 

Linux0.99.11, 24 July 1993 


buf or pat h points to an invalid address 

An I/O error occurred while reading from or writing to thefilesystem. 

fd is not a valid open file descriptor, 
but points to an invalid address 

An I/O error occurred while reading from or writing to thefilesystem. 


Linux 0.99.11, 24 July 1993 


swapon, swapoff 

swapon, swapoff— Start/stop swapping to fil^device 

SYNOPSIS 

#include <unistd.h> 

#include <linux/swap.h> 

int swapon(const char ‘path, int swapflags); 

int swapoff(const char ‘path); 
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DESCRIPTION 

swapon sets the swap area to thefileor block device specified by path, swapoff stops swapping to thefileor block device 
specified bypath. 

swapon takes a swapf i ags argument. If swapf i ags has the swap_flag_prefer bit turned on, the new swap area will have a higher 
priority than default. The priority isencoded as (prio « swap_flag_prio_shift) & swap_flag_prio_mask. Thesefunctions 
may only be used by the superuser. 

PRIORITY 

Each swap area has a priority, either high or low. The default priority is low. Within the low-priority areas, newer areas are of 
even lower priority than older areas. 

All priorities set with swapf i ags are high priority, higher than the default. They may have any non-negative value chosen by 
the caller. H igher numbersmean higher priority. 

Swap pages are allocated from areas in priority order, highest priority first. For areas with different priorities, a higher- 
priority area is exhausted before using a lower-priority area. If two or more areas have the same priority, and that is the 
highest priority available, pages are allocated on a round-robin basis between them. 

As of Linux 1.3.6, the kernel usually follows these rules, but there are exceptions. 

RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 

ERRORS 

M any other errors besides the following can occur if path is not valid: 

eperm The user is not the superuser, or more than max_swapfiles (defined to be 8 in Linux 1.3.6) are in 

use. 

einval Returned if path exists, but is neither a regular path nor a block device. 

enoent Returned if pat h does not exist. 

enomem Returned if there is insufficient memory to start swapping. 

C0NF0RMST0 

These functions are Linux specific. 

NOTES 

The partition or path must be prepared with mkswap(8). 

HISTORY 

The second (swapfiags) argument wasintroduced in Linux 1.3.2. 

SEE ALSO 

mkswap(8), swapon(8), swapoff(8) 

Linux 1.3.6, 22July 1995 


symlink 

symiink— M akes a new name for a file 
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SYNOPSIS 

#include <unistd.h> 

int symlink(const char *oIdpat h, const char *newpat h); 

DESCRIPTION 

symiink createsa symbolic link named oi dpat h that containsnewpat h . 

Symbolic links are interpreted at runtime, as if thecontents of the link were substituted into the path being followed to find 
a file or directory. 

Symbolic links may contain .. path components that (if used at the start of the link) refer to the parent directories of theone 
in which the link resides. 

A symbolic link (also known as a soft link) can point to an existing file or to a nonexistent one; the latter case is known as a 
dangling link. 

The permissions of a symbolic link are irrelevant; the ownership is ignored when following the link, but is checked when 
removal or renaming of the link is requested and the link is in a directory with the sticky bit set. 

If newpat h exists, it will not be overwritten. 

RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 

ERRORS 

EPERM 
EFAULT 
EACCES 

ENAMETOOLONG 
ENOENT 

ENOTDIR 
ENOMEM 
EROFS 
EEXIST 
ELOOP 

ENOSPC 

NOTES 

N 0 checking of oi dpat h isdone 

Deleting the name referred to by a symiink will actually delete thefile (unless it also has other hard links). If this behavior is 
not desired, use link. 

C0NF0RMST0 

SVID, AT & T, PO SIX, BSD 4.3 

BUGS 

Seeopen(2) regarding multiplefiles with the same name, and N FS. 


Thefilesystem containing pathname does not support the creation of symbolic links, 
sitjath or newpat h points outside your accessible addressspace 

W rite access to the directory containing newpat h is not allowed for the process's effective UID, or 
oneof the directories in newpat h did not allow search (execute) permission, 
oi tlpat h or newpat h wastoo long. 

A directory component in newpat h does not exist or isa dangling symbolic link, or 0)tpat h isthe 
empty string. 

A component used as a directory in newpat h isnot, in fact, a directory. 

I nsufficient kernel memory was available. 

T hefile is on a read-only filesystem, 
newpat h already exists. 

newpat h containsa reference to a circular symbolic link—that is, a symbolic link whose expansion 
contains a reference to itself. 

The device containing thefile has no room for the new directory entry. 
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SEE ALSO 

link(2), unlink(2), rename(2), open(2), lstat(2), ln(l), link(8) 


Linux, 24 July 1993 


sync 

sync— C ommits buffer cache to disk 

SYNOPSIS 

#include <unistd.h> 
int sync(void); 

DESCRIPTION 

sync first commits inodes to buffers, and then buffers to disk. 

RETURN VALUE 

sync always returns 0 . 

C0NF0RMST0 

SVID, AT&T,X/OPEN, BSD 4.3 

BUGS 

According to the standard specification (for example SVID),sync() schedules the writes, but it might return before the 
actual writing is done. However, since version 1.3.20, Linux does actually wait. (Thisstill does not guarantee data integrity; 
modern disks have large caches) 

SEE ALSO 

bdflush(2), fsync(2), fdatasync(2), update(8), sync(8) 

Linux 1.3.88,15 April 1995 


sysctl 

syscti— Read^writes system parameters 

SYNOPSIS 

#include <unistd.h> 

#include <linux/unistd.h> 

#include <linux/sysctl.h> 

_syscall1(int_sysctl , struct _sysctl_args *ar gs); 
int sysctl(struct _sysctl_args *ar gs); 

DESCRIPTION 

The syscti call reads and/or writes kernel parameters-for example, the hostname or the maximum number of open files 
The argument has the form 
struct _sysctl_args { 

int ‘name; /* integer vector describing variable */ 
int nlen; /* length of this vector */ 
void ‘oldval; /* 0 or address where to store old value */ 
size_t ‘oldlenp; /* available room for old value, 
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overwritten by actual size of old value */ 
void *newval; /* 0 or address of new value */ 
size_t newlen; /* size of new value */ 

}; 

Thiscall doesasearch in a tree structure possibly resembling a directory tree under /proc/sys, and, if the requested item is 
found, calls some appropriate routine to read or modify the value 

EXAMPLE 

#include <linux/unistd.h> 

#include <linux/types.h> 

#include <linux/sysctl.h> 

_syscall1(int, _sysctl, struct _sysctl args *, args); 

int sysctl(int ‘name, int nlen, void *oldval, size_t *oldlenp, 
void *newval, size_t newlen) 

struct _sysctl_args args={name,nlen,oldval,oldlenp,newval,newlen}; 

return _sysctl(&args); 


#define SIZE(x) sizeof(x)/sizeof (x[0]) 
#define OSNAMESZ 100 

char osname[OSNAMESZ]; 
int osnamelth; 

int name[ ] = { CTL_KERN, KERN_OSTYPE }; 


main(){ 

osnamelth = SIZE(osname); 

if (sysctl(name, SIZE(name), osname, &osnamelth, 0, 0)) 
perror("sysctl"); 

printf("This machine is running %*s\n", osnamelth, osname); 

} 

RETURN VALUES 

Upon successful completion, sysctl returns 0. Otherwise a value of-1 is returned, and errno issetto indicate the error. 

ERRORS 

ENOTDIR name was not found. 

eperm No search permission for one of the encountered directories, or no read permission where 0! dva 1 

was nonzero, or no write permission wherenewvai was nonzero. 
efault Theinvocation asked for the previous value by settingtpflai non-N ULL, but allowed zero room 

C0NF0RMST0 

Thiscall is Linux specific. 

HISTORY 

A sysctl call has been present in Linux since version 1.3.57. It originated in BSD-4.4. Only Linux has the/proc/sys mirror, 
and the object-naming schemes differ between Linux and BSD 4.4, but the declaration of the syscti(2) function isthesame 
in both. 



BUGS 

N ot all available objects are properly documented. 

It is not yet possible to change operating system by writing to /proc/sys/kernei/ostype. 

SEE ALSO 

proc(5) 

Linux 1.3.85,11 April 1996 


sysfs 

sysfs— Gets filesystem type information 

SYNOPSIS 

int sysfs(int option, const char * f s n a me); 

int sysfs(int opti on, unsigned int fsj ndex, char * but ); 

int sysfs(int option); 

DESCRIPTION 

sysfs returns information about the filesystem types currently present in the kernel. The specific form of the sysfs call and 
the information returned depend on the option in effect. You can 

■ Translate the filesystem identifier string fs name into a filesystem typeindex. 

■ Translate the filesystem type index f s_ i ndex into a null-terminated filesystem identifier string. This string will be written 
to the buffer pointed to by t j f . M ake sure that buf has enough space to accept the string. 

■ Return thetotal number of filesystem types currently present in the kernel. 

The numbering of thefilesystem typeindexes begins with 0. 

RETURN VALUE 

On success, sysfs returnsthefilesystem index for thefirst option, 0 for the second option, and the number of currently 
configured filesystems for the third option. On error, -1 isreturned, and errno isset appropriately. 

ERRORS 

einval f s n a me isnot a valid filesystem type identifier; f s_ i ndex isout of bounds; opt i on isinvalid. 

efault Either fsname or buf isoutsideyouraccessibleaddressspace. 

C0NF0RMST0 

System V 

Linux 1.3.16, 9 August 1995 

sysinfo 

sysinfo— Returnsinformation on overall system statistics 

SYNOPSIS 

As of Linux 0.99.10 and image release 4.4, 

#include <linux/kernel.h> 

#include <linux/sys.h> 

int sysinfo(struct sysinfo *info); 
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DESCRIPTION 

sysinfo returns information in the following structure: 

struct sysinfo { 
long uptime; 
unsigned long loads[3]; 
unsigned long totalram; 
unsigned long freeram; 
unsigned long sharedram 
unsigned long bufferram 
unsigned long totalswap 
unsigned long freeswap; 
unsigned short procs; 
char _f[22]; 

}; 

sysinfo provides a simple way of getting overall system statistics. This is more portablethan reading /dev/kmem. 

RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 

ERRORS 

efault The pointer to struct sysinfo is invalid. 

C0NF0RMST0 

Thisfunction is Linux specific. 

BUGS 

The Linux DLL 4.4.1 libraries do not contain a proper prototype for thisfunction. 

Linux0.99.10,24 July 1993 


I* Seconds since boot */ 

/* 1, 5, and 15 minute load averages */ 
/* Total usable main memory size */ 

/* Available memory size */ 

/* Amount of shared memory */ 

/* Memory used by buffers */ 

/* Total swap space size */ 

/* swap space still available */ 

/* Number of current processes */ 

/* Pads structure to 64 bytes */ 


syslog 

sysiog— Reads and/or clears kernel message ring buffer; sets consoie_iogievei 

SYNOPSIS 

#include <unistd.h> 

#include <linux/unistd.h> 

_syscall3(int syslog, inttype, char *b u f p , intlen); 
int syslog(int type, char *buf p, int len); 

DESCRIPTION 

This is probably not the function you are interested in. Look at sysiog(3) for the C library interface. This page only 
documents the bare kernel system call interface 
Thetype argument determines the action taken by sysiog. 

From kernel/printk.c:/* 

Valid commands to sysiog are 
o-Closethelog. Currently a NOP. 

1- Open the log. Currently a NOP. 

2- Read from the log. 
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s/slog 


3— Read up to the last 4K B of messages in the ring buffer. 

4— Read and clear last 4KB of messages in the ring buffer. 

5— Clear ring buffer. 

6— D isable printksto console 

7— Enable printksto console 

8— Set level of messages printed to console 
Only function 3 is allowed to non-root processes 

THE KERN EL LOG BUFFER 

The kernel has a cyclic buffer of length log_buf_len (4096) in which messages given as argument to the kernel function 
printk() are stored (regardless of their loglevel). 

The call sysiog (2, b u f ,i en ) waits until this kernel log buffer is nonempty, and then reads at mosti en bytes into the buffer 
buf.lt returns the number of bytes read. Bytes read from the log disappear from the log buffer; the information can only be 
read once This is the function executed by the kernel when a user program reads/proc/kmsg. 

Thecall sysiog (3 , b u f ,i en) will read the last i en bytes from thelog buffer (nondestructively), but will notread more than 
was written into the buffer since the last "clear ring buffer" command (which does not clear the buffer at all). It returns the 
number of bytes read. 

Thecall sysiog ( 4 ,buf ,i en) does precisely the same, but also executesthe "clear ring buffer" command. 

Thecall sysiog ( 5 , dummy ,i dummy) only executes the "clear ring buffer" command. 

THE LOGLEVEL 

The kernel routine printko will print a message on the console only if it has a loglevel less than the value of the variable 
consol e_i ogi evei (initially default_console_loglevel (7), but set to 10 if the kernel command line contains the word debug, 
and to is in case of a kernel fault-the 10 and 15 are just silly, and are equivalent to 8). This variable is set (to a value in the 
range 1-8) by thecall sysiog (8, dummy ,vai ue). Thecall sysiog (type, dummy,i dummy) with type equal to 6 or 7, sets it to 1 
(kernel panicsonly) or 7 (all except debugging messages), respectively. 

Every text line in a message has itsown loglevel. This level is default_message_loglevel -1 (6) unless the line starts with <d> 
where d isa digit in the range 1-7, in which case the level isd. The conventional meaning of the loglevel is defined in <iinux/ 
kernel.h> asfollOWS 
#define KERN_EMERG "<0> 

#define KERN_ALERT "<1> 

#define KERN_CRIT "<2> 

#define KERN_ERR "<3> 

#define KERN_WARNING "<4> 

#define KERN_NOTICE "<5> 

#define KERN_INFO "<6> 

#define KERN_DEBUG "<7> 

RETURN VALUE 

In case of error, -i isreturned, and errno is set. On success, for type equal to 2, 3, or 4, sysiogo returns the number of bytes 
read; otherwise it returns 0. 

ERRORS 

eperm An attempt was made to change consoie_iogievei or clear the kernel message ring buffer by a 

process without root permissions 
einval Bad parameters. 

erestartsys System call was interrupted by a signal— nothing was read. 


/* system is unusable */ 
/* action must be taken immediately */ 

/* error conditions */ 
/* warning conditions */ 
/* normal but significant condition */ 
/* informational */ 
/* debua-level messaaes */ 
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CONFORMSTO 

Thissystem call is Linux specific. 

SEE ALSO 

syslog(3) 

Linux 1.2.9,11 Junel995 

termios,tcgetattr,tcsetattr, tcsendbreak,tcdrain, tcflush, 
tcflow, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, 
tcgetpgnp,tcsetpgrp 

termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush,tcflow, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, 
tcgetpgrp, tcsetpgrp- Get and set terminal attributes, do line control, get and set baud rate, get and set terminal foreground 
process group ID 

SYNOPSIS 

#include <termios.h> 

#include <unistd.h> 

int tcgetattr ( int fd, struct termios *t e r mi o s _ p ); 

int tcsetattr ( int f d, int opt i onal _act i ons , struct termios *termi os_p ); 
int tcsendbreak ( int fd, int duration ); 

int tcflush ( int fd, int queue.selector ); 

int tcflow ( int f d, int a c ti o n ); 

speed_t cfgetospeed ( struct termios *termi os_p ); 

int cfsetospeed ( struct termios *termios_p, speed_t speed ); 

speed_t cfgetispeed ( struct termios *termi os_p ); 

int cfsetispeed ( struct termios *termios_p, speed_t speed ); 

pid_t tcgetpgrp ( int fd ); 

int tcsetpgrp ( int fd, pid_t pgr pid ); 

DESCRIPTION 

The termios functions describe a general terminal interface that is provided to control asynchronous communications ports 

M any of the functions described herehaveateMfigs.p argument that is a pointer to a termios structure. This structure 

containsthefollowing members: 

tcflag_t cj flag; /* input modes */ 

tcflag_t c_o flag; /* output modes */ 

tcflag_t c_cflag; /* control modes */ 

tcflag_t c_l flag;/*local modes*/ 

cc_t c_cc [NCOS] ; /* control chars */ 

Thefollowing arethecj flag flag constants 

ignbrk Ignore break condition on input. 

brkint If ignbrk isnot set, generate sigint on break condition; otherwise, read break as character \0. 

ignpar Ignoreframing errorsand parity errors. 

parmrk If ignpar isnot set, prefix a character with a parity error or framing error with \377 \0. If neither 

ignpar nor parmrk isset, read a character with a parity error or framing error as\0. 
inpck Enable input parity checking. 





termios, tcgdtattr, tc&attr, tcsndbreak, tcdrain, tcfludi, teflon, cfgdiospeed, cfgetispeed, cfastispeed, 

cf&ospeed, tegetpg-p, tesetpgrp 


875 


istrip Strip off the eighth bit. 

inlcr Translate N L to CR on input. 

igncr Ignore carriage return on input. 

icrnl T ranslate carriage return to newline on input (unless igncr is set). 

iuclc M ap uppercase characters to lowercase on input. 

ixon EnableXON/XOFF flow control on output. 

ixany E nable any character to restart output. 

ixoff EnableXON/XOFF flow control on input imaxbel ring bell when input queue isfull. 

Thefollowing are the c_ofiag flag constants 

opost Enableimplementation-defined output processing. 

olcuc M ap lowercase characters to uppercase on output. 

onlcr M ap N L to C R-N L on output. 

ocrnl M ap C R to N L on output. 

onocr D on't output C R at column 0. 

onlret Don't output CR. 

ofill Send fill characters for a delay rather than use a timed delay. 

ofdel Fill character is ASCI I DEL. If unset, fill character isASCII NUL. 

nldly N ewline delay mask. Values are nlb and nli . 

crdly Carriage-rdturn delay mask. Values are cro, cri, cr 2 , and cr3 . 

tabdly FI orizontal-tab delay mask. Values are tab®, tabi , tab 2 , tab3 , and xtabs. A value of xtabs expands 

tabs to spaces (with tab stops every eight columns). 
bsdly Backspace delay mask. Values areBso and bsi. 

vtdly Vertical-tab delay mask. V alues are vto and vti . 

ffdly Form-feed delay mask. V alues are ffo and ffi . 

Thefollowing are the c_cfiag flag constants 

csize C haracter size mask. V alues are css, cs6, csz.and css. 

cstopb Set two stop bits rather than one 

oread Enable receiver. 

parenb Enable parity generation on output and parity checking for input. 

parodd Parity for input and output isodd. 

hupcl Lower modem control lines after last processdosesthedevice(hangsup). 

clocal Ignore modem control lines. 

cibaud Mask for input speeds (not used). 

crtscts Flow control. 

Thefollowing are the c_ifiag flag constants 

isig W hen any of the characters intr, quit, susp, or dsusp are received, generate the corresponding 

signal. 

icanon Enables canonical mode. This allows the special characters eof, eol, eol 2 , erase, kill, reprint, 

status, and werase, and also buffers by lines 

xcase If icanon isalso set, terminal is uppercase only. Input isconverted to lowercase, except for 

characters preceded by \. 0 n output, uppercase characters are preceded by \, and lowercase 
characters are converted to uppercase. 

Echo input characters 


ECHO 
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echoe If icanon isalso set, the erase character erases the preceding input character, and werase erases the 

preceding word. 

echok If icanon isalso set, the kill character erases the current line 

echonl If icanon isalso set, echo the nl character even If echo is not set. 

echoctl If echo isalso set, ASCII control signals other than tab, nl, start, and stop are echoed asCtrl+X, 

whereX is the character with ASCII code 0x10 greater than thecontrol signal. For example, 
character 0x28 (BS) isechoed asCtrl +H. 

echoprt If icanon and i echo are also set, charactersare printed as they are being erased. 

echoke If icanon isalso set, kill isechoed by erasing each character on the line as specified by echoe and 

echoprt. 

flusho Output is being flushed. Thisflag istoggled by typing the discard character. 

noflsh Disables flushing of the input and output queues when generating the sigint and sigquit signals, 

and flushing of the input queue when generating the sigsusp signal. 
tostop Sends the sigttou signal to the process group of a background process that tries to write to its 

controlling terminal. 

pendin All characters in the input queue are reprinted when the next character is read, (bash handles 

typeahead this way.) 

iexten Enable implementation-defined input processing. 

tcgetattro gets the parameters associated with the object referred by f d and stores them in thetermios structure referenced 
by ter mi os p . Thisfunction may be invoked from a background process; however, the terminal attributesmay be subse¬ 
quently changed by a foreground process. 

tcsetattro sets the parameters associ ated with the terminal (unless support is required from the underlying hardware that is 
not available) from the termios structure referred to by t e r mi o s _ p . o p t i o n a i _ a c t i o r s specifi es when the changes take effect: 
tcsanow T he change occurs immediately. 

tcsadrain The change occurs after all output written to f d hasbeen transmitted. Thisfunction should be used 

when changing parameters that affect output. 

tcsaflush T he change occurs after all output written to the object referred to by f d has been transmitted, and 

all input that hasbeen received but notread will be discarded before the change is made. 

tcsendbreako transmitsa continuous stream of zero-valued bits for a specific duration, if theterminal is using asynchronous 
serial data transmission. If Jurat i on isa, it transmits zero-valued bits for at least 0.25 seconds, and not more than 0.5 
seconds If dur at i on isnoto, it sends zero-valued bits for d u r a t i on*N seconds, where N is at least 0.25, and not more 
than 0.5. 

If theterminal is not using asynchronous serial data transmission, tcsendbreako returns without taking any action, 
tcdratno waits until all output written to the object referred to by f d has been transmitted. 

tcfiusho discards data written to the object referred to by f d but not transmitted, or data received but not read, depending 
on the value Ofqueue.selector: 
tciflush Flushesdata received but not read. 

tcoflush Flushesdata written but not transmitted. 

tcioflush Flushes both data received but not read and data written but not transmitted. 

tcfiowo suspends transmission or reception of data on the object referred to by f d , depending on the value of act on: 

tcooff Suspends output. 

tcoon Restarts suspended output. 

tcioff T ransmitsa stop character, which stops theterminal device from transmitting data to thesystem. 

tcion T ran sm its a start character, which starts the terminal de/ice transmitting data to thesystem. 



termios, tcgdtattr, tcsdtattr, tcsndbreak, tcdrain, tcfludi, teflon, cfgdiospeed, cfgetispeed, cfastispeed, 

cfaetospeed, tegetpg-p, tesetpgrp 


FI 


The default on open of a terminal file isthat neither its input nor its output issuspended. 

The baud rate functions are provided for getting and setting the values of the input and output baud rates in the termios 
structure. The new values do not take effect until tesetattro is successfully called. 

Setting the speed to bo instructs the modem to hang up. The actual bit rate corresponding to B384oo may be altered with 
setserial(8). 

Theinput and output baud rates are stored in thetermios structure. 

ctgetospeedo returns theoutput baud rate stored in thetermios structure pointed to by ter mi os. p. 

ctsetospeedo sets theoutput baud rate stored in thetermios structure pointed to by||i|i as.p to speed, which must be one 

of these constants: 

B0 

B50 

B75 

B110 

B134 

B150 

B200 

B300 

B600 

B1200 

B1800 

B2400 

B4800 

B9600 

B19200 

B38400 

B57600 

B115200 

B230400 

Thezero baud rate, bo, is used to terminate the connection. If bo is specified, the modem control lines will no longer be 
asserted. Normally, this will disconnect the line CBAUDExisa mask for the speeds beyond those defined in POSIX.1 (57600 
and later). Thus, B57600 & cbaudex is nonzero, 
cfgetispeed 0 returns theinput baud rate stored in thetermios structure. 

cfsetispeedo sets theinput baud rate stored in thetermios structure to speed. If theinput baud rate i s set to 0, it will be 
equal to theoutput baud rate 

tcgetpgrpo returns the process group ID of the foreground processing group, or -1 on error. 

tesetpgrp 0 sets the process group ID to pgrpid. pgrpid must be the ID of a process group in the same session. 

RETURN VALUES 

cfgetispeed 0 returns theinput baud rate stored in thetermios structure, 
ctgetospeedo returns theoutput baud rate stored in thetermios structure 
tcgetpgrpo returns the process group ID of foreground processing group, or -1 on error. 

All other functions return 
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0 0 n success 

-i on failure (and set emno to indicatetheerror). 


SEE ALSO 

setserial(8) 


Linux, 25 February 1995 


time 

time- Gets time in seconds 

SYNOPSIS 

#include <time.h> 
time_t time(time_t *t ); 

DESCRIPTION 

time returns the time since 00:00:00 GMT, January 1,1970, measured in seconds. 

If t is non null, the return value is also stored in the memory pointed to byt. 

C0NF0RMST0 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

(Under BSD 4.3, thiscall is made obsolete by gettimeofday(2).) 

SEE ALSO 

ctime(3), date(l), ftime(3), gettimeofday(2) 

Linux, 24 July 1993 


times 

times— G ets process times 

SYNOPSIS 

#include <sys/times.h> 
clock_t times(struct tms *buf); 


DESCRIPTION 

times stores the current process timesin but. 
struct tms isasdefined in /usr/include/sys/times.h: 
struct tms { 



/* system time */ 

/* user time of children */ 

/* system time of children */ 


times returnsthe number of clock ticks that have elapsed si nee thesystem has been up. 



truncate ftruncate 
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CONFORMSTO 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

SEE ALSO 

time(l), getrusage(2), wait(2) 

Linux0.99.11, 24 July 1993 

truncate,ftruncate 

truncate, ftruncate—T runcate a file to a specified length 

SYNOPSIS 



DESCRIPTION 

truncate causes thefile named bypath or referenced by f d to betruncatedtoatmosti ength bytes in size. Ifthefile 
previously was larger than this size, the extra data is lost. W ith ftruncate, thefile must be open for writing. 

RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 

ERRORS 

The errors for truncate are 

enotdir A component of the path prefix is not a directory. 

einval The pathname contains a character with the high-order bit set. 

enametoolong A component of a pathname exceeded 255 characters, or an entire pathname exceeded 1,023 

characters. 

enoent Thenamedfiledoesnotexist. 

eacces Search permission is denied for a component of the path prefix. 

eacces The named file is not writeable by the user. 

eloop Too many symbolic linkswere encountered in translating the pathname 

eisdir Thenamedfileisadirectory. 

erofs T he named file resides on a read-only filesystem. 

etxtbsy Thefileisapureprocedure(sharedtext) filethat is being executed. 

eio An I/O error occurred updating the inode 

efault path points outside the process's allocated address space. 

The errors for ftruncate are 
ebadf f d is not a valid descriptor. 

einval f d references a socket, not a file 

einval fd is not open for writing. 

HISTORY 

These function callsappeared in BSD 4.2. 
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BUGS 

These calls should be generalized to allow ranges of bytes in afileto be discarded. 

SEE ALSO 

open(2) 

BSD Man Page 24July 1993 

umask 

mask- Sets a file-creation mask 

SYNOPSIS 

#include <sys/stat.h> 
int umaskfint mask); 

DESCRIPTION 

umask sets the umask to mask 4 0777. 

RETURN VALUE 

The previous value of the mask is returned. 

C0NF0RMST0 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

SEE ALSO 

creat(2), open(2) 

Linux 24 July 93 


uname 

uname—Gets name and information about the current kernel 

SYNOPSIS 

#include <sys/utsname.h> 
int uname(struct utsname *buf ); 

DESCRIPTION 

uname returns system information in but .The utsname struct is as defined in /usr/inciude/sys/utsname.h: 
struct utsname { 

char sysname[65]; 
char nodename[65]; 
char release[65]; 
char version[65]; 
char machine[65]; 
char domainname[65]; 


RETURN VALUE 

On success, 0 is returned. On error, -1 is returned, and errno 


is set appropriately. 





afs_ys:all, break, gtty, lock, mpx, prof, quotactl, stty, ustat 
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ERRORS 

efault buf isnot valid. 

C0NF0RMST0 

SVID, AT&T, POSIX,X/OPEN 

SEE ALSO 

uname(l), getdomainname(2), gethostname(2) 

Linux 0.99.11 24]uly93 


none 

none- U ndocumented system calls 

SYNOPSIS 

U ndocumented system calls. 

DESCRIPTION 

As of Linux 1.3.88, there are 163 system calls listed in /usr/inciude/asm/unistd.h. This man page mentionsthose calls that 
are implemented in the kernel but not yet documented in man pages Someof these calls do not yet have prototypes in the 
libc include files 


SOLICITATION 

If you have information about these system calls, please look in thekernel source code, write a man page (using a style similar 
to that of the other Linux section 2 man pages), and send it to aeb@cwi.ni for inclusion in the next man page release from the 
Linux Documentation Project. 


STATUS 

Undocumented are insync, readv, writev, getsid, fdatasync, sysctl, sched_setparam, sched_getparam, sched_setscheduler, 
sched_getscheduler, sched_yield, sched_get_priority_max, sched_get_priority_min, sched_rr_get_interval. 


SEE ALSO 

obsolete(2), unimplemented(2) 


Linux 1.3.8612 April 1996 


af s_syscall, break, gtty, lock, mpx, prof, quotactl, stty, ustat 

afs_syscall, break, gtty, lock, mpx, prof, quotactl, stty, ustat—U nimplemented system calls 

SYNOPSIS 

Unimplemented system calls 

DESCRIPTION 

These system calls are not implemented in theLinux 1.2.4 kernel. 

RETURN VALUE 

These system calls always return -i and set errno to enosys. 
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SEE ALSO 

obsolete(2), undocumented^) 


Linux 1.2.4,15 April 1995 


unlink 

unlink—Deletes a name and possibly thefile it refers to 

SYNOPSIS 

#include <unistd.h> 

int unlink(const char ‘pathname); 

DESCRIPTION 

unlink deletes a name from thefilesystem. If that name was the last link to afileand no processeshave thefile open, thefile 
is deleted, and the space it was using is made available for reuse 

If the name was the last link to a file but any processes still have thefile open, thefile will remain in existence until the last 
filedescriptor referring to it isclosed. 

If the name referred to a symbolic link, the link is removed. 

If the name referred to a socket, fifo, or device, the name for it is removed but processes that havetheobject open can 
continue to use it. 

RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 

ERRORS 

EFAULT 
EACCES 

EPERM 

ENAMETOOLONG 
ENOENT 
ENOTDIR 
EISDIR 
ENOMEM 
EROFS 

C0NF0RMST0 

SVID, AT&T, POSIX, X/OPEN , BSD 4.3 

BUGS 

Infelicities in the protocol underlying N FS can cause the unexpected disappearance of files that are still being used. 

SEE ALSO 

link(2), rename(2), open(2), rmdir(2), mknod(2), mkfifo(3), remove(3), rm(l), unlink(8). 


pat hname points outside your accessi ble address space. 

Write access to the directory containing pat hname is not allowed for the process's effective U ID, or 
oneof the directories in pat hname did notallow search (execute) permission. 

The directory containing pat hname has the sticky bit (s_isvtx) set, and the process's effective U ID is 
neither theU ID of thefile to be deleted nor that of the directory containing it, or pat hname is a 
directory. 

pathname WaStOO long. 

A directory component in pat hname does not exist or isa dangling symbolic link. 

A component used as a directory in pathname is not, in fact, a directory, 
pathname refers to a directory. 

I nsufficient kernel memory was available, 
pathname refersto a file on a read-only filesystem. 


Linux, 24July 1993 




uselib 

useiib— Selects shared library 

SYNOPSIS 

#include <unistd.h> 

int uselib(const char ‘library); 

DESCRIPTION 

useiib selects the shared library binary that will be used by this process 

RETURN VALUE 

On success 0 is returned. On error, -1 isreturned, and errno is set appropriately. 

ERRORS 

In addition to all the error codes returned by open(2) and mmap(2), the following may also be returned: 

enoexec Thefile specified by 1 i brary is not executable, ordoesnothavethecorrect magic numbers 

eacces T he library specified by 1 i br ar y is not readable. 

C0NF0RMST0 

useiib)) is Linux specific. 

SEE ALSO 

open(2), mmap(2), ldd(l), gcc(l), ar(l), ld(l) 

Linux 0.99.11, 24 July 1993 


ustat 

ustat—Gets filesystem statistics 

SYNOPSIS 

#include <sys/types.h> 

int ustat(dev_t dev, struct ustat * u b u f); 

DESCRIPTION 

ustat returns information about a mounted filesystem, dev is a device number identifying a device containing amounted 

filesystem, ubuf isa pointer to a ustat structure that contains thefollowing members: 

daddr_t f_tfree; /* Total free blocks */ 

ino_t f_tinode; /* Number of free inodes */ 

char f_fname[6]; /* Filsys name */ 

char f_fpack[6]; /* Filsys pack name */ 

The last two fields, f_fname and f_fpack, are not implemented and will always be filled with null characters. 

RETURN VALUE 

On success, 0 isreturned, and the ustat structure pointed to by ubuf will be filled in. On error, -1 isreturned, and errno is 
set appropriately. 
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ERRORS 

einval dev does not refer to a device containing a mounted filesystem. 

efault ubuf points outside of your accessible address space 

enosys The mounted filesystem referenced by dev does not support this operation, or any version of Linux 

before 1.3.16. 

NOTES 

ustat has been provided for compatibility only. All new programs should usestatfs(2) instead. 

HISTORY 

ustat was first implemented in Linux 1.3.16. All versions of Linux before 1.3.16 will return enosys. 

C0NF0RMST0 

System V 

SEE ALSO 

statfs(2), stat(2) 

Linux 1.3.16, 9Augustl995 


utime,utimes 

utime, utimes- C hange access and/or modification times of an inode 

SYNOPSIS 

#include <sys/types.h> 

//include <utime.h> 

int utime(const char ‘filename, struct utimbuf *buf); 

//include <sys/time.h> 

int utimesfchar ‘filename, struct timeval *tvp); 

DESCRIPTION 

utime changes the access and modification times of the inode specified by f i i ename to the act i me and modti me fields of but, 
respectively. If buf isN ULL, the access and modification times of the file are set to the current time The utimbuf structure is 
struct utimbuf { 

time_t actime; /* access time */ 
time_t modtime; /* modification time */ 

}; 

In the Linux DLL 4.4.1 libraries, utimes isjust a wrapper for utime, tvp[ 0 ].tv_sec isacti me, andtvp m.tv_sec is modti me. 

The timeval structure is 

struct timeval { 

long tv_sec; /* seconds */ 

long tv_usec; /* microseconds */ 


RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 



vm86 


ERRORS 

Other errors may occur. 

eaccess Permission to writethefile isdenied. 

ENOENT fi I ename does not exist. 

C0NF0RMST0 

utime:SVID,POSIX 
utimesiBSD 4.3 

SEE ALSO 

stat(2) 


Linux, 10Junel995 


vhangup 

vhangup— Virtually hangs up the current tty 

SYNOPSIS 

#include <unistd.h> 
int vhangup(void); 

DESCRIPTION 

vhangup simulates a hangup on the current terminal. This call arrangesfor other users to have a clean tty at login time 

RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 

ERRORS 

eperm The user is not the superuser. 

SEE ALSO 

init(8) 

LinuxO.99.11, 24July 1993 


vm86 

vm86— Enters virtual 8086 mode 

SYNOPSIS 

#include <sys/vm86.h> 

int vm86(struct vm86_struct * info); 

DESCRIPTION 

EnterVM 86 mode with information as specified in i nf 0 : 
struct vm86_struct { 

struct vm86_regs regs; 
unsigned long flags; 
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unsigned long screen_bitmap; 


struct vm86_regs { 

* normal regs, with special meaning for the segment descriptors.. 

long ecx; 
long edx; 
long esi; 

long ebp; 
long eax; 

long _null_ds; 

long _null_es; 

long _null_fs; 

long __null_gs; 
long orig_eax; 
long eip; 

long eflags; 
long esp; 

* these are specific to v86 mode: 

long ds; 
long fs; 
long gs; 


these are specific to v86 mode: 


long fs; 
long gs; 

RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 

ERRORS 

eperm Saved kernel stack exists 


Linux 0.99.11, 24 July 1993 


wait, waitpid 

wait, waitpid— W ait for process termination 

SYNOPSIS 

#include <sys/types.h> 

//include <sys/wait.h> 





wait, waitpid 



DESCRIPTION 

The wait function suspends execution of the current process until a child has exited, or until a signal is delivered whose 
action isto terminate the current processor to call a signal-handling function. If a child has already exited by the time of the 
call (a so-called zombie process), the function returns immediately. Any system resources used bythechild are freed. 

The waitpid function suspends execution of the current process until a child as specified by the pi d argument has exited, or 
until a signal is delivered whose action isto terminate the current process or to call a signal-handling function. Just as with 
wait, if achild requested by p i d has already exited by the time of the call, the function returns immediately. Any system 
resources used bythechild are freed. 

The value of pi d can be one of the following: 

< -i Wait for any child process whose process group ID is equal to the absolute value of pi d. 

-i Wait for any child process;thisisthesamebehaviorthatwaitexhibit& 

0 Wait for any child process whose process group ID is equal to that of the calling process. 

> 0 Wait for the child whose process ID is equal to the value of pi d. 

The value of opt ons isan OR of zero or more of thefollowing constants: 
wnohang Return immediately if no child hasexited. 

wuntraced Also return for children that are stopped and whose status has not been reported. 

If status isnot null, wait or waitpid stores status information in the location pointed to bystati oc. 

Thisstatuscan be evaluated with thefollowing macros (these macros take the stat buffer as an argument—not a pointer to 
the buffer!): 

wiFExiTED(status) Is nonzero if thechild exited normally. 

wexitstatus (status ) Evaluates to the least significant eight bits of the return code of thechild that terminated, which 

may have been set as the argument to a cal I to exit o or as the argument for a return statement 
in the main program. This macro can only be evaluated if wifexited returned nonzero. 
wiFsiGNALED(st at us ) Returns true if the child process exited because of a signal that was not caught. 

wTERMSiG(st at us ) Returns the number of the signal that caused thechild process to terminate. This macro can 

only be evaluated if wifsignaled returned nonzero. 

wifstopped(s t at us ) Returns true if the child process that caused the return is currently stopped; this is only possible 

if the call was done using wuntraced. 

wsTOPSiG(st at us ) Returns the number of the signal that caused thechild to stop. This macro can only be 

evaluated if wifstopped returned nonzero. 

RETURN VALUE 

The process ID of the child that exited returns-i on error or 0 if wnohang was used and no child was available (in which case 
errno isset to an appropriate value). 

ERRORS 

echild If thechild process specified in pi d does not exist. 

eperm If the effective user ID of the calling process does not match that of the process being waited 

for, and the effective user ID of the calling process is not that of the superuser. 
erestartsys If wnohang was not set and an unblocked signal or asiGCHLD was caught; this is an extension to 

the PO SIX.1 standard. 
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CONFORMSTO 

POSIX.1 

SEE ALSO 

signal(2), wait4(2), signal(7) 


Linux, 24July 1993 


wait3,wait4 

wait3,wait4— Wait for process termination, BSD style 

SYNOPSIS 

#define _USE_BSD 
#include <sys/types.h> 

#include <sys/resource.h> 

//include <sys/wait.h> 

pid_t wait3(int ‘status ,int opt ions , 

struct rusage *rus age); 

pid_t wait4(pid_t pi d,int*st at us ,int options , 
struct rusage ‘rusage); 

DESCRIPTION 

T he wait3 function suspends execution of the current process until a child has exited, or until a signal isdelivered whose 
action is to terminate the current process or to call a signal-handling function. If a child has already exited by the time of the 
call (a zombie process), the function returns immediately. Any system resources used by thechild are freed. 

T he wait4 function suspends execution of the current process until a child as specified bythepi d argument has exited, or 
until a signal isdelivered whose action is to terminate the current process or to call a signal-handling function. If a child as 
requested by pi d has already exited by the time of the call (a zombie process), thefunction returns immediately. Any system 
resources used by thechild are freed. 

The value of pi d can be one of the following: 

< -i Wait for any child process whose process group ID is equal to the absolute value of pi d. 

-i Wait for any child process; this is equivalent to callingwait3. 

0 Wait for any child process whose process group ID is equal to that of the calling process. 

> 0 Wait for the child whose process ID is equal to the value of pi d. 

The value of opt i ons isan exdusiveOR of zero or more of the following constants: 

wnohang Return immediately if no child is there to be waited for. 

wuntraced Also return for children that are stopped and whose status has not been reported. 

If status is not null, wait3 and wait4 store status information in the location pointed to bystati oc. 

This status can be evaluated with thefollowing macros: 
wifexited(*s t at us ) Is nonzero if thechild exited normally. 

wexitstatus (‘status ) Evaluates to the least significant eight bits of the return code of thechild that terminated, which 
may have been set as the argument to a call to exit or as the argument for a return statement in 
the main program. This macro can only be evaluated if wifexited returned nonzero. 
wifsignaled (‘status ) Returns true if the child process exited because of a signal that was not caught. 

wTERMSiG(*st at us ) Returnsthe number of thesignal that caused thechild processto terminate. This macro can 

only be evaluated if wifsignaled returned nonzero. 




write 


wiFSTOPPED(*st at us ) Returns true if the child process that caused the return is currently stopped; this is only possible 

ifthecallwasdoneusing wuntraced. 

wsTOPSiG(*st at us ) Returnsthe number of thesignal that caused thechild to stop. This macro can only be 

evaluated ifwiFSTOPPED returned nonzero. If r usage is not null, the struct rusage as defined in 
<sys/resource.h> it points to will be filled with accounting information. Seegetrusage(2) for 
details. 

RETURN VALUE 

These calls return the process ID of thechild that exited, -i on error, or 0 if wnohang was used and no child was available (in 
which caseerrno will be set appropriately). 

ERRORS 

echild If thechild process specified in pi d does not exist. 

eperm If the effective user ID of the calling process does not match that of the process being waited 

for, and the effective user ID of the calling process is not that of the superuser. 
erestartsys If wnohang was not sdt and an unblocked signal or asiGCHLD was caught; this is an extension to 

thePOSIX.1 standard. 


C0NF0RMST0 

POSIX.1 

SEE ALSO 

signal(2), getrusage(2), wait(2), signal(7) 


Linux, 24July 1993 


write 

write- W rites to a file descriptor 

SYNOPSIS 

#include <unistd.h> 

ssize_t write(int f d, const void *buf , size_t count); 


DESCRIPTION 

write writes up to count bytes to the file referenced by the file descriptor f d from the buffer starting at but. PO SIX requires 
that a reado that can be proved to occur after a write 0 returned returns thenew data. Note that not all filesystems are 
POSIX conforming. 

RETURN VALUE 

On success, the number of byteswritten is returned (0 indicates nothing was written). On error, -1 is returned, and errno is 
set appropriately. If count is@ and thefile descriptor refers to a regular file, 0 will be returned without causing any other 
effect. For a special file, the results are not portable. 

ERRORS 

ebadf f d is not a valid file descriptor or is not open for writing. 

einval td is attached to an object that is unsuitable for writing. 

efault but isoutside your accessible address space. 
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epipe f d is connected to a pipe or socket whose reading end is closed. When this happens, the writing 

process will receive a sigpipe signal; if it catches, blocks, or ignores this, the error epipe is 
returned. 

eagain Non-blocking I/O has been selected using o_nonblock, and there was no room in the pipe or 

socket connected to f d to write thedata immediately. 

eintr Thecall was interrupted by a signal before any data was written. 

enospc Thedevicecontainingthefilereferred to by f d has no room for the data. 

0 ther errors may occur, depending on the object connected to f d . 

C0NF0RMST0 

SVID, AT & T, PO SIX, X/O PEN , BSD 4.3 

SEE ALSO 

open(2), read(2), fcntl(2), close(2), lseek(2), select(2), ioctl(2), fsync(2), fwrite(3) 

Linux, 13 January 1996 




Part III: 


Library Functions 
























Part III: L ibrary Functions 


892 


Intro 

DESCRIPTION 

This chapter describes all the library functions, excluding the library functions described in Part 2, which implement system 
calls The various function groups are identified by a letter that isappended to thechapter number: 

(3C) These functions—the functions from Chapter 2 and from Chapter 3S— are contained in theC standard 

library libc, which will be used by cc(l) by default. 

(3S) T hese functions are parts of the stdio(3S) library. They are contained in thestandard C library libc. 

(3M ) These functions are contained in the arithmetic library nbm. They are used by the f77(l) FORTRAN 

compiler by default, but not by thecc(l) C compiler, which needs the option -1 m. 

(3F) T hese functions are part of the F0 RT RAN library libm. T here are no special compiler flags needed to 

use these functions. 

(3X) Various special libraries Themanual pagesdocumentingtheirfunctionsspecify thelibrary names. 

AUTHORS 

Look at the header of the manual page for the author(s) and copyright conditions Note that these can be different from page 
to page! 

Linux, 13 December 1995 


abort 

abort— Causesabnormal program termination 

SYNOPSIS 

#include <stdlib.h> 
void abort(void); 

DESCRIPTION 

The aborto function causes abnormal program termination unless the signal sigabort is caught and the signal handler does 
not return. Ifthe abort!) function causes program termination, all open streams are closed and flushed. 

If the sigabort function isblocked or ignored, the abort!) function will still override it. 

RETURN VALUE 

T he abort o function never returns 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

sigaction(2), exit(3) 

GNU, 12 April 1993 


abs 

abs- C omputes the absolute value of an integer 



SYNOPSIS 

#include <stdlib.h> 
int abs(int j ); 

DESCRIPTION 

Theabso function computes the absolute value of theinteger argument]. 

RETURN VALUE 

Returns the absolute value of the integer argument. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

NOTES 

T rying to take the absolute value of the most negative i nteger is not defined. 

SEE ALSO 

ceil(3), floor(3), fabs(3), labs(3), rint(3) 

GNU, 6Junel993 


acos 

acos—Arc cosine function 

SYNOPSIS 

#include <math.h> 
double acos(double x); 

DESCRIPTION 

T he acos () function calculates the arc cosine of x; that is the value whose cosine is x . If x falls outside the range -1 to 1, 
acos() failsand errnoisset. 

RETURN VALUE 

T he acos o function returns the arc cosine in radians; the value is mathematically defined to be between 0 and pi (inclusive). 

ERRORS 

edom x is out of range 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

asin(3), atan(3), atan2(3), cos(3), sln(3), tan(3) 

8Junel993 


acosh 

acosh-1 nverse hyperbolic cosine function 
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SYNOPSIS 

#include <math.h> 
double acosh(double *); 

DESCRIPTION 

Theacosho function calculates the inverse hyperbolic cosine of x; that isthe value whose hyperbolic cosine isx. If* is less 
than 1.0, acosho returnsnot-a-number (N aN), and errno isset. 

ERRORS 

edom x is out of range. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

asinh(3), atanh(3), cosh(3), sinh(3), tanh(3) 

13Junel993 


alloca 

aiioca— M emory allocator 

SYNOPSIS 

#include <stdllb.h> 
void ‘alloca( size_t size); 

DESCRIPTION 

The aiioca function allocates size bytes of space i n the stack frame of the caller. T h i s temporary space is automatically freed 
on return. 

RETURN VALUES 

The aiioca function returns a pointer to the beginning of the allocated space. If the allocation fails, a null pointer is 
returned. 

C0NF0RMST0 

There is evidence that the aiioca function appeared in 32 v, pwb, pwb.2, 3bsd, and 4bsd. There is a man page for it in BSD 
4.3. Linux usestheGN U version. 

BUGS 

T he aiioca function is machine dependent. 

SEE ALSO 

brk(2), pagesize(2), calloc(3), malloc(3), realloc(3) 

GNU, 29 November 1993 


asin 


asin— Arc sine function 



SYNOPSIS 

#include <math.h> 
double asin(double x); 

DESCRIPTION 

Theasino function calculates the arc sine of x, which isthe value whose sine isx. If x falls outside the range-1 to 1, asino 
failsand emno isset. 

RETURN VALUE 

Theasino function returns the arc sine in radians, and the value is mathematically defined to be between -pi/2 and pi/2 
(inclusive). 

ERRORS 

edom x is out of range. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

acos(3), atan(3), atan2(3), cos(3), sin(3), tan(3) 

8Junel993 


asinh 

asinh— I nverse hyperbolic sinefunction 

SYNOPSIS 

#include <math.h> 
double asinh(double x); 

DESCRIPTION 

The asinh () function calculates the inverse hyperbolic sine of x— that is, the value whose hyperbolic sine isx. 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

acosh(3), atanh(3), cosh(3), sinh(3), tanh(3) 

13Junel993 


assert 

assert- Abort the program if assertion isfalse 


SYNOPSIS 
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DESCRIPTION 

assert o printsan error message to standard output and terminates the program by calling abort o if express i on isfalse (that 
is, evaluates to 0). This only happens when the macro ndebug is undefined. 

RETURN VALUE 

No value is returned. 

C0NF0RMST0 

ISO9899 (ANSI C) 

BUGS 

asserto is implemented asa macro; if the expression tested has side effects, program behavior will be different depending on 
whether ndebug is defined. This may create Heisenbugs, which go away when debugging isturned on. 

SEE ALSO 

exit(3), abort(3) 

GNU, 4 April 1993 


atan 

atan— Arc tangent function 

SYNOPSIS 

#include <math.h> 
double atanfdouble x); 

DESCRIPTION 

T he atan () function calculates the arc tangent of x - that is, the value whose tangent is x . 

RETURN VALUE 

Theatano function returns the arc tangent in radians, and the value is mathematically defined to be between -pi/2 andpi /2 
(inclusive). 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

acos(3), asin(3), atan2(3), cos(3), sin(3), tan(3) 

8Junel993 


atan2 

atan2— Arc tangent function of two variables 

SYNOPSIS 


#include <math.h> 

double atan2(double y, double x); 
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DESCRIPTION 

The atan2() function calculates the arc tan gent of the two variables, * and ?. It is similar to calculating the arc tangent of y/x, 
except that the sines of both arguments are used to determine the quadrant of the result. 

RETURN VALUE 

The atan2() function returnsthe result in radians, which is between -pi and pi (inclusive). 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

acos(3), asin(3), atan(3), cos(3), sin(3), tan(3) 

8Junel993 


atanh 

atanh— I nverse hyperbolic tangent function 

SYNOPSIS 

#include <math.h> 
double atanh(double *); 

DESCRIPTION 

T he atanh o function calculates the inverse hyperbolic tangent of *; that is the value whose hyperbolic tangent isx. If the 
absolute value of * is greater than 1.0, acosho returns not-a-number (N aN), and errno is set. 

ERRORS 

edom x is out of range. 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

asinh(3), acosh(3), cosh(3), sinh(3), tanh(3) 

13Junel993 


atexit 

atexit- Register a function to be called at normal program termination 

SYNOPSIS 

#include <stdlib.h> 


DESCRIPTION 

The atexit o function registers the given function to be called at normal program termination, whether via exit(2) or via 
return from the program's main. Functionsso registered are called in the reverse order of their registration; no arguments are 
passed. 
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RETURN VALUE 

T he atexitf (function returns the value 0 if successful; otherwise, thevalue-i is returned, and the global variableerrno isset 
to indicate the error. 

ERRORS 

enomem Insufficient memory availableto add thefunction. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

exit(3), on exit(3) 

GNU, 29 March 1993 


atof 

atof— Convert a string to a double 

SYNOPSIS 

#include <stdlib.h> 

double atof(const char *nptr); 

DESCRIPTION 

T he atof 0 function convertsthe initial portion of the string pointed to by n p t r to double. The behavior is the same as 

strtod(nptr, (char “(NULL); 

except that atof () does not detect errors 

RETURN VALUE 

The converted value 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

atoi(3), atol(3), strtod(3), strtol(3), strtoul(3) 

GNU, 29 March 1993 


atoi 

atoi— Convert a string to an integer 

SYNOPSIS 

#include <stdlib.h> 

int atoi(const char *npt r); 



bcmp 



DESCRIPTION 

Theatoif) function convertsthe initial portion of the string pointed to by nptr to int. The behavior isthe same as 

strtol(nptr, (chan **)NULL, 10); 

except that atoi( ) does not detect errors 

RETURN VALUE 

The converted value 


C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

atof(3), atol(3), strtod(3), strtol(3), strtoul(3) 

GNU, 29 March 1993 


atol 

atoi— Convert a string to a long integer 

SYNOPSIS 

#include <stdlib.h> 

long atol(const char *npt r); 

DESCRIPTION 

Theatoio function convertsthe initial portion of the string pointed to by nptr to long. The behavior isthe same as 

strtol(nptr, (char **)NULL, 10); 

except that atoi( ) does not detect errors 

RETURN VALUE 

The converted value 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

atof(3), atoi(3), strtod(3), strtol(3), strtoul(3) 

GNU, 29 March 1993 


bcmp 

bcmp- C ompare byte strings 

SYNOPSIS 

#include <string.h> 

int bcmp(const void *sl, const void *s 


;2, int n); 
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DESCRIPTION 

The bcmpo function compares the first n bytes of the strings si and s 2 . If thetwo strings are equal, bcmpo returnso; 
otherwise it returns a nonzero result. If n iso, thetwo strings are assumed to be equal. 

RETURN VALUE 

The bcmpo function returnso if the strings are equal; otherwise, a nonzero result is returned. 

C0NF0RMST0 

4.3BSD .Thisfunction isdeprecated— use memcmp in new programs. 

SEE ALSO 

memcmp(3), strcasecmp(3), strcmp(3), strcoll(3), strncmp(3), strncasecmp(3) 

GNU, 9 April 1993 


bcopy 

bcopy— Copy byte strings 

SYNOPSIS 

#include <string.h> 

void bcopy (const void *src, void*dest , int n); 

DESCRIPTION 

The bcopy o function copies the first n bytes of the source stri ng s r c to the destination string dest . If n isO, no bytes are 
copied. 

RETURN VALUE 

T he bcopy o function returns no value. 

C0NF0RMST0 

4.3BSD.Thisfunction isdeprecated-usememcpyin new programs. 

SEE ALSO 

memccpy(3), memcpy(3), memmove(3), strcpy(3), strncpy(3) 

GNU, 9 April 1993 


bsearch 

bsearch— Binary search of a sorted array. 

SYNOPSIS 

#include <stdlib.h> 

void *bsearch(const void *key, const void 'base, size_t nmemb, 
size_t size,int(*compar )(const void *, const void *)); 

DESCRIPTION 

The bsearch o function searches an array of nmemb objects, the initial member of which is pointed to by iM.e, for a member 
that matches the object pointed to bykey. The size of each member of the array is specified by size. 

The contents of the array should be in ascending sorted order according to the comparison function referenced by c o mp a r. 



htonl, htons, ntohl, ntohs 




Thecompar routine is expected to ha/e two arguments that point to thekey object and to an array member, in that order, and 
should return an integer less than, equal to, or greater than 0, respectively, if the key object isfound to be less than, match, or 
be greater than the array member. 

RETURN VALUE 

Thebsearcho function returns a pointer to a matching member of thearray, or null if no match isfound. If there are 
multiple elements that match thekey, the element returned is unspecified. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

qsort(3) 

GNU, 29 March 1993 

bcmp, bcopy, bzero, memccpy, memchr, memcmp, memcpy, memf rob, 
memmem,memmove, memset 

bcmp, bcopy, bzero, memccpy, memchr, memcmp, memcpy, memf rob, memmem, memmove, memset— Byte String operations 

SYNOPSIS 

//include <string.h> 

int bcmp(const void *$ 1 , const void *s 2 , int n); 
void bcopy(const void *src, void *dest , int n); 
void bzero(void *s, int n); 

void *memccpy(void *dest , const void *src, int c, size_t n); 

void *memchr(const void *s , int c, size_t n); 

int memcmp(const void *sl, const void *s 2 , size_t n ); 

void ‘memcpy(void *dest , const void *src, size_t n); 

void *memfrob(void *s , size_t n); 

void ‘memmem(const void ‘needle, size_t need I elen, 

void ‘memset(void *s , int c, size_t n); 

DESCRIPTION 

The byte string functions perform operations on strings that are not NULL terminated. Seetheindividual man pages for 
descriptions of each function. 

SEE ALSO 

bcmp(3), bcopy(3), bzero(3), memccpy(3), memchr(3), memcmp(3), memcpy(3), memfrob(3), memmem(3), memmove(3), memset(3) 

GNU, 12 April 1993 


htonl, htons, ntohl, ntohs 

htom, htons, ntohl, ntohs— Convert values between host and network byte order 


SYNOPSIS 

//include <netinet/in.h> 

unsigned long int htonl(unsigned long int host long); 
unsigned short int htons(unsigned short int hostshort); 
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unsigned long int ntohl(unsigned long int net long); 
unsigned short int ntohs(unsigned short int net shor t); 

DESCRIPTION 

Thehtomo function converts the long integer host i ong from host byte order to network byte order. 

Thehtonso function converts the short integer host short from host byte order to network byte order. 

Thentoh) o function convertsthe long integer net i ong from network byte order to host byte order. 

T he ntohsf) function convertsthe short integer net short from network byte order to host byte order. 

On the i80x86, the host byte order is least significant byte first, whereas the network byte order, as used on the Internet, is 
most significant byte first. 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

gethostbyname(3), getservent(3) 

BSD, 15 April 1993 



bzero 

bzero— W rites os to a byte string 

SYNOPSIS 

#include <string.h> 
void bzero(void *s, int n); 

DESCRIPTION 

T he bzero o function sdtsthe first n bytes of the byte strings toO. 

RETURN VALUE 

The bzero o function returns no value. 

C0NF0RMST0 

4.3BSD .Thisfunction isdeprecated— use memset in new programs. 

SEE ALSO 

memset(3), swab(3) 

GNU, 9 April 1993 


catgets 

catgets— G dts message from a message catalog 

SYNOPSIS 

#include <features.h> 

#include <nl_types.h> 

char *catgets(nl_catd catalog, int set_number, int 
message_number, char ‘message); 
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DESCRIPTION 

catgetso reads the message message_number, in set set_number, from the message catalog identified by cat ai og. (cat a i og isa 
catalog descriptor returned from an earlier call to catopen(3).) Thefourth argument message points to a default message 
string that will be returned by catgetso if the identified message catalog is not currently open or is damaged. The message 
text is contained in an internal buffer area and should be copied by the application if it is to be saved or modified. The return 
string is always terminated with a null byte. 

RETURN VALUES 

On success, catgetso returns a pointer to an internal buffer area containing the null-terminated message string, catgetso 
returns a pointer to message if it fails because the message catalog specified by catalog is not currently open. 0 therwise, 
catgetso returns a pointer to an empty string if the message catalog is available but does not contain the specified message 

NOTES 

These functions are only available in iibc.so.4.4.4c and above. 

SEE ALSO 

catopen(3), setlocale(3) 

29 November 1993 


catopen,catclose 

catopen, catclose— 0 pen/close a message catalog 

SYNOPSIS 

#include features.h> 

#include <nl_types.h> 

nl catd catopen(char ‘name, int flag); 

void catclose(nl_catd catalog); 

DESCRIPTION 

catopeno opens a message catalog and returns a catalog descriptor, na me specifies the name of the message catalog to be 
opened. If name specifies an absolute path (that is, contains a/), name specifies a pathnamefor the message catalog. Otherwise, 
the environment variable nlspath is used, with name substituted for %n (see iocaie(5)). If nlspath does not exist in the 
environment, or if a message catalog cannot be opened in any of the paths specified by nlspath, thefollowingpathsare 
searched in order: 

/etc/locale/LCJJIESSAGES 

/usr/lib/locale/LCJIESSAGES 

/usr/lib/locale/name/LC_MESSAGES 

I n all cases, lc_messages stands for the current setting of the lcjiessages category of locale from a previous call to 
setiocaieo and defaults to the C" locale. In the last search pathname refers to the catalog name. 

Thef i ag argument to catopen is used to indicate the type of loading desired. Thisshould be either MCLoadBySet orMCLoadAii. 
The former value indicates that only the required set from the catalog is loaded into memory when needed, whereas the latter 
causes the initial call to catopeno to load the entire catalog into memory. 

catclose () doses the message catalog identified by cat ai og. It invalidates any subsequent references to the message catalog 
defined by cat ai og. 

RETURN VALUES 

catopeno returns a message catalog descriptor of type m_catd on success. 0 n failure it returns -i. 
catcioseo returns® on success, or -i on failure. 
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NOTES 

These functions are only available in libc.so.4.4.4c and above. In the case of Linux, the catalog descriptor ni_catd isactually 
an area of memory assigned bymmapo and not a file descriptor, thus allowing catalogsto be shared. 

SEE ALSO 

catgets(3), setlocale(3) 

30 November 1993 


ceil 

ceil- Smallest integral value not less than x 

SYNOPSIS 

#include <math.h> 
double ceil (double *); 

DESCRIPTION 

Theceiio function rounds up* to the nearest integer, returning that value asa double. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

abs(3), fabs(3), floor(3), labs(3), rint(3) 

6Junel993 


clientlib 

ciientub — N NTP clientlib part of InterNdtNewslibrary 

SYNOPSIS 

extern FILE *ser_rd_fp; 
extern FILE *ser_wr_fp; 
extern char ser_line[]; 
char * getserverbyfile(fiI e); 
char ‘file; int server_init(host); 

int handle_server_response(response, host); 

void put_server(te*t ); 

int get_server(buf f, buffsi ze); 


DESCRIPTION 

The routines described in this manual page are part of the I nterNdtNews library, iibinn(3). They are replacements for the 
clientlib part of the N NTP distribution, and are intended to be used in building programssuch asrrn. 
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getserverbyfiie calls Getconfigvaiue to get the name of the local N NTP server. It returns a pointer to static space. Then i e 
parameter is ignored. 

server_init opens a connect to the N N T P server at the specified host . It returnsthe server's response code or -i on error. If 
a connection was made, ser_rd_f p and ser_wr_f p can be used to read from and write to the server, respectively, and ser_iine 
will contain the server's response ser_nne can also be used in other routines 

handie_server_response decodes the response, which comes from the server on host . If the client is authorized, it returns®. A 
clientthat isonly allowed to read isauthorized, but handie_server_response will print a message on the standard output. If 
the client is not authorized to talk to the server, a message is printed, and the routine returns -i. 
put_server sends the text in buff totheserver, adding the necessary N NTP lineterminators and flushing thel/O buffer. 
get_server reads a line of text from the server i nto buff, reading at most buff size characters Any trailing \r\n terminators 
are stripped off. get_server returns-i on error. 

ciose_server sends a quit command to the server and closes the connection. 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

libinn(3) 

clock 

clock— D etermine processor time 

SYNOPSIS 

ffinclude <time.h> 
clock_t clock(void); 

DESCRIPTION 

The clock o function returnsan approximation of processor time used by the program. 

RETURN VALUE 

The value returned is the CPU time used so far as a ciock_t; to get the number of seconds used, divide by clocks_per_sec. 

C0NF0RMST0 

ANSI C 

BUGS 

T he C standard allows for arbitrary values at the start of the program; take the difference between the value returned from a 
call to clock) ) at the start of the program and the value returned at the end for maximum portability. 

The times)) function call returns more information. 

SEE ALSO 

times(2) 

GNU, 21 April 1993 


closedir 

ciosedii — C lose a directory 
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SYNOPSIS 

//include <sys/types.h> 

//include <dirent.h> 
int closedir(DIR *dir ); 

DESCRIPTION 

Theciosediro function closes the directory stream associated with dir. The directory stream descriptor di r is not available 
after this call. 

RETURN VALUE 

Theciosediro function returns 0 on success or-1 on failure. 

ERRORS 

ebadf Invalid directory stream descriptor di r. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3 

SEE ALSO 

close(2), opendir(3), readdir(3), rewinddir(3), seekdir(3), telldir(3), scandir(3) 

11]unel995 


confstr 

confstr— Gdt configuration-dependent string variables 

SYNOPSIS 

#define _USE_P0SIX_2 
#include <unistd.h> 

size_t confstr(int name, char *buf , size_t len); 

DESCRIPTION 

confstr/) gets the value of configuration-dependent string variables. 

Thename argument is the system variable to be queried. The following variables are supported: 

cs_path A value for the path variable that indicates where all the POSIX. 2 standard utilities can be found. 

If buf is not NULL, and 1 en isnot 0, confstro copiesthe value of the string to but truncated to len-1 characters if necessary, 
with a null character as termination. Thiscan be detected by comparing the return value of confstr 0 against 1 en. 

If len iso and buf iSNULL, confstr!) just returnsthe value in Return Value. 

RETURN VALUE 

If name does not correspond to a valid configuration variable confstro returns0. 

EXAMPLES 

Thefollowing code fragment determines the path where you can find the POSIX.2 system utilities: 

char ‘pathbuf; size_t n; 

n = confstr(_CS_PATH,NULL,(size_t)0); 

if ((pathbuf = malloc(n)) == NULL) abort)); 

confstr(_CS_PATH, pathbuf, n); 



ERRORS 

If the value of name is invalid, errno is set to EINVAL. 

C0NF0RMST0 

Proposed POSIX.2 

BUGS 

POSIX.2 is not yet an approved standard; the information in this man page is subject to change 

SEE ALSO 

sh(1), exec(2), system(3) 

GNU, 17 April 1993 


copysign 

copysign— Copiesthesign of anumber 

SYNOPSIS 

#include <math.h> 

double copysign(double *, double y); 

DESCRIPTION 

Thecopysigno function returnsa value whose absolute value matches*, but whose sign matches that of y. 

C0NF0RMST0 

BSD 4.3 

GNU, 6Junel993 


COS 

cos— Cosinefunction 

SYNOPSIS 

#include <math.h> 
double cosfdouble *); 

DESCRIPTION 

Thecoso function returns the cosine of x, where* isgiven in radians 

RETURN VALUE 

Thecoso function returnsa value between -1 and 1. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

acos(3), asln(3), atan(3), atan2(3), sin(3), tan(3) 


8Junel993 
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cosh 

cosh- H yperbolic cosine function 

SYNOPSIS 

#include <math.h> 
double coshfdouble x); 

DESCRIPTION 

Thecoshf) function returns the hyperbolic cosine of x, which isdefined mathematically as (exp(x)+exp(-x))/ 2 . 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

acosh(3), asinh(3), atanh(3), sinh(3), tanh(3) 

13Junel993 


crypt 

crypt— Password and data encryption 

SYNOPSIS 

#include <unistd.h> 

char *crypt(const char *key, const char *salt); 

DESCRIPTION 

crypt isthe password-encryption function. It is based on the D ata Encryption Standard algorithm, with variations intended 
(among other things) to discourage the use of hardware implementations of a key search, 
key is a user's typed password. 

salt is a two-character string chosen from the set [a-zA-zg-g./]. This string is used to perturb the algorithm in one of 4,096 
different ways. 

By taking the lowest seven bits of each character of the key, a 56-bit key is obtained. This 56-bit key is used to repeatedly 
encrypt a constant string (usually a string consisting of all 0s). The returned value points to the encrypted password, a series 
of 13 pri ntabl e A SC 11 characters (with thefirsttwo characters representing the salt itself). The return value points to static 
data whose content is overwritten by each call. 

W arning: The key space consists of equal 7.2ei6 possible values. Exhaustive searches of this key space are possible using 
massively parallel computers. Software, such ascrack(l), isavailableto search the portion of this key space that is generally 
used by humansfor passwords. Hence password selection should, at minimum, avoid common words and names Using a 
passwd(l) program thatchecksfor crackable passwords during the selection process is recommended. 

The D ES algorithm itself has a few quirks that make using thecrypt(3) interface a very poor choice for anything other than 
password authentication. If you are planning to usethecrypt(3) interface for a cryptography project, don't do it; get a good 
book on encryption and one of the widely available D ES libraries instead. 

C0NF0RMST0 

SVID, X/O PEN, BSD 4.3 
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SEE ALSO 

login(l), passwd(l), encrypt(3), getpass(3), passwd(5) 


3 September 1994 


ctenmid 

ctermid— Gets controlling terminal name 

SYNOPSIS 

#include <stdio.h> 
char ‘ctermid(char *s); 

DESCRIPTION 

ctermid( ) returns a string that is the pathname for the current controlling terminal for this process. If s is null, a static buffer 
is used; otherwise, s points to a buffer used to hold the terminal pathname The symbolic constant L_ctermid isthe 
maximum number of characters in the returned pathname 

RETURN VALUE 

This function returns the pointer to the pathname. 

C0NF0RMST0 

POSIX.1 

BUGS 

The path returned might not uniquely identify the controlling terminal; it might, for example be /dev/tty. 

It is not assured that the program can open theterminal. 

SEE ALSO 

ttyname(3) 

GNU, 6 April 1993 


asctime,ctime,gmtime,localtime,mktime 

asctime, ctime, gmtime, localtime, mktime— T ransform binary date and time to ASC11 

SYNOPSIS 

#include <time.h> 

char ‘asctime(const struct tm ‘timeptr); 
char *ctime(const time_t *timep); 
struct tm *gmtime(const time_t *t i mep); 
struct tm *localtime(const time_t *t i mep); 
time_t mktime (struct tm ‘timeptr); 
extern char *tzname [2]; 

extern int daylight; 

DESCRIPTION 

Thecttmeo, gmtimef ), and locaitime ((functions all take an argument of data type time_t, which represents calendar time. 
When interpreted as an absolute time value it represents the number of seconds elapsed since 00:00:00 on January 1,1970, 
Coordinated Universal Time(UTC). 
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Theasctimeo and mktimeo functions both take an argument representing broken-down time, which isa binary representa¬ 
tion separated into year, month, day, and so on. Broken-down time is stored in the structure tm, which is defined in <time.h> 
asfollows 



T he members of the t m structure are 

tm_sec The number of seconds after the minute, normally in the range 0 to 59, but can be up to 61 to allow for 

leap seconds. 

tmjnin T he number of minutes after the hour, in the range 0 to 59. 

tm_hour T he number of hours past midnight, in the range 0 to 23. 

tmjnday T he day of the month, in the range 1 to 31. 

tm_mon The number of monthssincejanuary, in the range 0 to 11. 

tm_year The number of years since 1900. 

tm_wday The number of days since Sunday, in therangeOto 6. 

tm_yday T he number of days since J anuary 1, in the range 0 to 365. 

tm_isdst A flag that indicates whether daylight savings timeis in effect at the time described. The value is positive if 

daylight saving time is in effect, 0 if it is not, and negative if the information is not available 

The ctime( (function converts the calendar timet i mep into a string of the form 

"Wed Jun 30 21:49:08 1993\n" 

Theabbreviationsforthedaysof the week are sun, Mon , Tue, wed, Thu, Fri, and sat. The abbreviationsfor the months are 
Jan, Feb, Mar, Apr, May, jun, jui, Aug, Sep, Oct, Nov, and Dec. The return value points to a statically allocated string that might 
be overwritten by subsequent calls to any of the date and time functions The function also sets the external variable tzname 
with information about the current time zone 

Thegmtimeo function converts the calendar timetimep to broken-down time representation, expressed in Coordinated 
Universal Time(UTC). 

The iocaitime o function converts the calendar timet i mep to broken-time representation, expressed relative to the user's 
specified time zone. The function sets the external variablest z name with information about the current time zone ti me zone 
with the difference between Coordinated Universal Time and local standard time in seconds, and dayi i ght to a nonzero 
value if standard U .S. daylight saving time rules apply. 

Theasctimeo function converts the broken-down time value ti mept r into a string with the same format asctime(). The 
return value points to a statically allocated string that might be overwritten by subsequent calls to any of the date and time 
functions 

The mktimeo function converts a broken-down time structure expressed as local time, to calendar time representation. The 
function ignores the specified contents of the structure members tm_wday and tm_yday and recomputes them from the other 
information in the broken-down timestructure Calling mktimeo also sets the external variable tzname with information 
about the current time zone. If the specified broken-down time cannot be represented as calendar time mktimeo returnsa 
value of (time_t) (-i) and does not alter the tm_nd ay and members of the broken-down timestructure 





CONFORMSTO 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

date(l), gettimeofday(2), time(2), tzset(3), difftime(3), stnftime(3), newctime(3) 

BSD, 26 April 1996 


difftime 

difftime— C alculates time difference 

SYNOPSIS 

#include <time.h> 

double difftime(time_t timel, time_t t i me 0 ); 

DESCRIPTION 

T he dif f timed function returns the number of seconds elapsed between timet i mei and timet i me o. The two times are 
specified in calendar time which represents the time elapsed since 00:00:00 on January 1,1970, Coordinated Universal 
Time(UTC). 

CONFORMSTO 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

date(l), gettimeofday(2), time(2), ctime(3), gmtime(3), localtime(3) 

GNU, 2July 1993 


div 

div- Computes the quotient and remainder of integer division 

SYNOPSIS 

#include <stdlib.h> 

div_t div(int numer , int denom) ; 

DESCRIPTION 

Thedivo function computes the value nu me r/denom and rdturnsthe quotient and remainder in a structure named div_t that 
contains two integer members named quot and rem. 

RETURN VALUE 

T he div_t structure. 

CONFORMSTO 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

ldiv(3) 

6Junel993 
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drand48, erand48,lrand48, nrand48,mrand48,j rand48,srand48, 
seed48,lcong48 

drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48— G enerate Uniformly distributed pseudo¬ 
random numbers 

SYNOPSIS 

#include <stdlib.h> 
double drand48(void); 

double erand48(unsigned short int xsubi [3]); 
long int lrand48(void); 

long int nrand48(unsigned short int xsubi [3]); 
long int mrand48(void); 

long int jrand48(unsigned short int xsubi [3]); 

unsigned short int * seed48(unsigned short int seedl6v [3]); 
void lcong48(unsigned short int param[7]); 


DESCRIPTION 

These functions generate pseudo-random numbers using the linear congruential algorithm and 48-bit integer arithmetic. 
Thedrand48() and erand48( ) functions return non-negative double-precision floating-point values uniformly distributed 
between [0.0,1.0]. 

The irand48( ) and nrand48( ) functions return non-negative long integers uniformly distributed between 0 and 2~31. 
Themrand48() and jrand48( ) functions return signed long integers uniformly distributed between -2^31 and 2'31. 
Thesrand48(),seed48(), and icong48() functions are initialization functions, oneof which should be called before using 
drand48(), irand48(), or mrand49( ). The functions erand48(), nrand48(), and jrand48() do not require an initialization 
function to be called first. 

All thefunctions work by generating a sequence of 48-bit integers, Xi, according to the linear congruential formula 
X/+l=(aX/-te) mod m, where/ >=0 

The parameter m=2-48; hence 48-bit integer arithmetic is performed. Unless icong48() iscalled, a and care given by 

a = 0X5DEECE66D 
c = 0xB 


The value returned by any Of the functions drand48(), erand48(), lrand48(), nrand48(), mrand48(), Or jrand48() iSCOmputed 
by first generating the next 48-bit xi in the sequence. T hen the appropriate number of bits, according to the type of data 
item to be returned, is copied from the high-order bits of xi and transformed into the returned value. 

Thefunctions drand48(), irand48<), and mrand48( ) store the last 48-bit xi generated in an internal buffer. Thefunctions 
erand48(), nrand48<), and jrand48() require the calling program to provide storage for the successive xi values in thearray 
argument xsubi . T he functionsare initialized by placing the initial value of xi into thearray before calling the function for 
the first time 

The initializer function srand48() sets the high-order 32 bits of xi to the argument seedva . The low-order 16 bits are set to 
the arbitrary value 0x330E. 

The initializer function seed48( ) sets the value of xi to the 48-bit value specified in the array argument seedl6v. The 
previous value of Xi iscopied into an internal buffer and a pointer to this buffer is returned byseed48(). 

The initialization function icong48() allowstheuserto specify initial values for x ,aand c. Array argument elements 
param[0-2] specify xi , param[3-5] specify a, and param[6] specifies c. After icong48() has been called, a subsequent call to 
either srand48() orseed48<) will restore the standard valuesof a andc. 



CONFORMSTO 

SVID 3 


NOTES 

These functions are declared obsolete by SVID 3, which states that rand(3) should be used instead. 

SEE ALSO 

rand(3), random(3) 

2 July 1993 


drem 

drem— Floating-point remainder function 

SYNOPSIS 

#include <math.h> 

double drem(double x, double y); 


DESCRIPTION 

Thedremo function computes the remainder of dividing x by y. The return value is x-n*y, where n is the quotient of x 
divided by y, rounded to the nearest integer. If the quotient is % it is rounded to the even number. 

RETURN VALUE 

T he drem o function returns the remainder unless y isO, in which case the function fails and errrto issdt. 

ERRORS 

edom T he denominator y is 0. 


CONFORMSTO 

BSD 4.3 

SEE ALSO 

fmod(3) 


6Junel993 


ecvt,fcvt 

ecvt, fcvt— Convert a floating-point number to a string 


SYNOPSIS 

#include <stdlib.h> 

char *ecvt(double number , size_t ndigi ts,int*decpt ,int*sign); 
char *fcvt(double number , size_t ndi gi ts,int*decpt ,int*sign); 

DESCRIPTION 

T he ecvt o function converts number to a NULL-terminated string of ndi gi ts digits and returns a pointer to the string. The 
string itself does not contain a decimal point; however, the position ofthedecimal point relative to the start of the string is 
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stored in dec pt. A negative value for dec pt means that the decimal point is to the left of the start of the string. If the sign of 
number is negative, si gn issdtto anonzero value; otherwise, it's set to 0 . 

T he tcvto function is identical to ecvto, except that ndi gits specifies the number of digits after the decimal point. 

RETURN VALUE 

Both the ecvto and tcvto functions return a pointer to a static string containing the ASCI I representation of number .The 
static string is overwritten by each call to ecvto or tcvto. 

SEE ALSO 

gcvt(3), sprintf(3) 

28 March 1993 


erf, erf c 

ert, ertc— Error function and complementary error function 

SYNOPSIS 

#include <math.h> 
double erf(double x); 
double ertc (double x); 

DESCRIPTION 

Theerto function returns the error function of x, defined as 
erf(x) = 2/sqrt(pi)* integral from 0 to x of exp(-t*t) dt 
Theerfco function returns the complementary error function of x — that is, l.O-erf(x). 

C0NF0RMST0 

SVID 3, BSD 4.3 

SEE ALSO 

exp(3) 

BSD, 25Junel993 


execl,execlp,execle, exect, execv, execvp 

execl, execlp, execle, exect, execv, execvp— Execute a file 

SYNOPSIS 

#include <unistd.h> 
extern char “environ; 

int execl(const char ‘path, const char *arg, ...); 
int execlp(const char ‘file, const char *arg, ...); 
int execle(const char ‘path, const char *arg, ...); 
int execlp(const char ‘file, const char *arg, ...); 
int execle(const char ‘path, const char *arg, ...); 

int execle(const char ‘path, const char *arg , .... char * const emp [ ]) ; 
int exect(const char ‘path, char ‘const ar g*[]); 
int execv(const char ‘path, char ‘const a r g* [ ]); 
int execvp(const char ‘file, char ‘const ar g v [ ]); 
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DESCRIPTION 

T he exec fami ly of functions replaces the current process image with a new process image T he functions described in this 
manual page are front ends for the function execve(2). (Seethe manual page for execve for detailed information about the 
replacement of the current process) 

The initial argument for these functions is the pathname of afilethat isto be executed. 

The const char *ar g and subsequent ellipses in the execi, execip, and execie functions can bethought of as arg@, argi. 

argn. T ogether they describe a list of oneor more pointers to null-terminated strings that represent the argument list 
available to the executed program. Thefirst argument, by convention, should point to the file name associated with thefile 
being executed. The list of arguments must determinated by a null pointer. 

The exect, execv, and execvp functions provide an array of pointers to null-terminated strings that represent the argument 
list available to the new program. Thefirst argument, by convention, should point to the filename associated with thefile 
being executed. The array of pointers must determinated by aNULL pointer. 

The execie and exect functions also specify the environment of the executed process by following the null pointer that 
terminatesthe list of arguments in the parameter list or the pointer to theargv array with an additional parameter. This 
additional parameter isan array of pointers to null-terminated strings and must determinated by aNULL pointer. The other 
functionstake the environment for the new process image from theexternal variableenvi ron in thecurrent process. 

Some of these functions have special semantics 

The functions execip and execvp will duplicate the actions of the shell in searching for an executable file if the specified 
filename does not contain a si ash (/) character. The search path isthepath specified in the environment by the path variable. 
If this variable isn't specified, thedefault path /bin:/usr/bin : is used (isthistrue for Linux?). In addition, certain errors are 
treated specially. 

If permission isdenied for a file (the attempted execve returned eacces), these functions will continue searching the rest of 
the search path. If no other file is found, however, they will return with the global variable errno set to eacces. 

If the header of a file isn’t recognized (theattempted execve returned ENO EXEC), these functions will execute theshell with 
the path of thefile as its first argument. (If this attempt fails, no further searching is done.) 

If thefile is currently busy (the attempted execve returned etxtbusy), these functions will sleep for several seconds, periodi¬ 
cally re-attempting to execute the file. (Isthistrue for Linux?) 

Thefunction exect executes a file with the program-tracing facilities enabled (see ptrace(2)). 

RETURN VALUES 

If any of the exec functions returns, an error will have occurred. The return value is-i, and the global variable errno will be 
set to indicate the error. 

FILES 

/bin/sh 

ERRORS 

execi, execie, execip, and execvp may fail and set errno for any of the errors specified for the library functions execve(2) and 
malloc(3). 

exect and execv may fail and set errno for any of the errors specified for the library function execve(2). 


SEE ALSO 

sh(1), execve(2), fork(2), trace(2), environ(5), ptrace(2) 

COMPATIBILITY 

H istorically, thedefault path for the execip and execvp functions was /bin:/usr/bin. This was changed to place the current 
directory last to enhance system security. 
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T he behavior of execip and execvp when errors occur while attempting to execute the file is historic practice, but has not 
traditionally been documented and is not specified by the PO SIX standard. 

T raditionally, the functions execip and execvp ignored all errors except for the ones described above and enomem and e 2 big, 
upon which they returned. They now return if any error other than the ones described in the "Errors" section occurs. 

STANDARDS 

execl, execv, execle, execip, and execvp conform to IEEE Stdl003.1-88 (PO SIX.1). 

BSD M an Page, 29 N ovember 1993 


errno 

errno — N umber of last error 

SYNOPSIS 

#include <errno.h> 
extern int errno; 


DESCRIPTION 


Theinteger errno isset by system calls (and some library functions) to indicate what went wrong. Its value issignificant only 
when the call returns an error (usually -1), and a library function that does succeed is allowed to change errno. 

Sometimes, when -i is also a legal return value, you have to set errno to 0 before the call in order to detect possible errors. 


POSIX lists the following symbolic error names: 


E2BIG 

EACCES 

EAGAIN 

EBADF 

EBUSY 

ECHILD 

EDEADLK 

EDOM 

EEXIST 

EFAULT 

EFBIG 

EINTR 

EINVAL 

EIO 

EISDIR 

EMFILE 

EMLINK 

ENAMETOOLONG 

ENFILE 

ENODEV 

ENOENT 

ENOEXEC 

ENOLCK 

ENOMEM 


Arg list too long 

Permission denied 

Resource temporarily unavailable 

Bad filedescriptor 

Resource busy 

N 0 child processes 

Resource deadlock avoided 

Domain error 

Fileexists 

Bad address 

Filetoo large 

Interrupted function call 

Invalid argument 

Input/output error 

Isa directory 

Too many open files 

Too many links 

Filename too long 

T00 many open files in system 

N 0 such device 

No such file or directory 

Exec format error 

No locks available 

N ot enough space 




exp, log, loglO, pow 




ENOSPC 

ENOSYS 

ENOTDIR 

ENOTEMPTY 

ENOTTY 

ENXIO 

EPERM 

EPIPE 

ERANGE 

EROFS 

ESPIPE 

ESRCH 

EXDEV 

SEE ALSO 

perror(3) 


exit 

exit- Causes normal program termination 

SYNOPSIS 

#include <stdlib.h> 

DESCRIPTION 

T he exit o function causes normal program termination, and the value of status is returned to the parent. All functions 
registered with atexito and on exito are called in the reverse order of their registration, and all open streams are flushed 
and closed. 

RETURN VALUE 

The exito function does not return. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

_exit(2), atexit(3), on_exit(3) 

GNU, 2 April 1993 


No space left on device 
Function not implemented 
N ot a directory 
D i rectory not empty 
Inappropriate I/O control operation 
N o such device or address 
0 peration not permitted 
Broken pipe 
Result too large 
Read-only filesystem 
Invalid seek 
N o such process 
Improper link 


21 July 1996 


exp, log, log10, pow 

exp, log, logio, pow— Exponential, logarithmic, and power functions 

SYNOPSIS 


#include <math.h> 
double exp(double x); 
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double log(double x); 
double log10(double x); 
double pow(double x, double y); 

DESCRIPTION 

The expo function rdturnsthevalueofe (the base of natural logarithms) raised to the power of x. 

The logo function returns the natural logarithm of x. 

The iogi®( ) function returnsthebase-10 logarithm of x. 

Thepowo function returns the value of x raised to the power of y. 

ERRORS 

The logo and logioo functions can return thefollowing errors 

edom Theargumentx is negative. 

erange Theargumentx iso. The log of 0 is not defined. 

Thepowo function can return thefollowing error: 

edom Theargumentx is negative and y is not an integral value This would result in a complex number. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

sqrt(3), cbrt(3) 

GNU Junel6,1993 



expml,loglp 

expmi, logip— Exponential minus 1, logarithm of 1 plus argument 

SYNOPSIS 

#include <math.h> 
double expml (double x); 
double loglp (double x); 

DESCRIPTION 

expmi (x) returnsa value equivalent to exp (x)-l. Itiscomputed in a way that is accurate even if the value of x is near 0-a 

case where exp (x)-1 would be inaccurate due to subtraction of two numbers that are nearly equal. 

iogi p (x ) returnsa value equivalent to log (1 +x). Itiscomputed in a way that is accurate even if the value of x is near 0. 

C0NF0RMST0 

BSD 

SEE ALSO 

exp(3), log(3) 


GNU, 16 September 1995 
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tabs 

F abs— A bso I ute val u e of f I oati n g- po i n t n um ber 

SYNOPSIS 

#include <math.h> 
double fabs(double x); 

DESCRIPTION 

T he f abs () function returns the absolute value of the floating-point number x. 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

abs(3), ceil(3), floor(3), labs(3), rint(3) 

25 Junel993 


fclose 

f close— C loses a stream 

SYNOPSIS 

#include <stdlo.h> 
int fclose(FILE ‘stream); 

DESCRIPTION 

The fclose function dissociates the named stream from its underlying fi le or set of functions. If the stream was being used for 
output, any buffered data iswritten first, using ffiush(3). 

RETURN VALUES 

Upon successful completion, 0 isreturned. Otherwise, eof isreturned, and the global variable ermo issetto indicate the 
error. In either case, no further access to the stream is possible 

ERRORS 

ebadf T he argument stream is not an open stream. 

T he fclose function may also fail and set errno for any of the errors specified for the routines ciose(2) or f f iush(3). 

SEE ALSO 

close(2), fflush(3), fopen(3), setbuf(3) 

STANDARDS 

Thefciose function conformsto AN SI C3.159-1989 ("AN SI C"). 

BSD M an Page, 29 N ovember 1993 


clearerr, feof, f error, fileno 

ciearerr, feof, ferror, fileno— C heck and resdt stream status 
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SYNOPSIS 

#include <stdio.h> 
void ciearerr) FILE ‘stream); 
int feof(FILE ‘stream); 
int ferror(FILE ‘stream); 
int fileno(FILE ‘stream); 

DESCRIPTION 

Thefunction ciearerr clears the end-of-file and error indicators for the stream pointed to bystream. 

Thefunction feof tests the end-of-file indicator for the stream pointed to by stream, returning nonzero if it isset. The end- 
of-file indicator can only be cleared by thefunction ciearerr. 

Thefunction terror tests the error indicator for the stream pointed to by stream, returning nonzero if it isset. The error 
indicator can only be reset by the ciearerr function. 

Thefunction tiieno examines the argument stream and returns its integer descriptor. 

ERRORS 

These functions should not fail and do not set the external variable errno. 

SEE ALSO 

open(2), stdio(3) 

STANDARDS 

The functions ciearerr, feof, and ferror conform to C3. 159-1989 ("ANSI C"). 

BSD M an Page, 29 N ovember 1993 


fflush,fpurge 

ffiush, fpurge— Flush a stream 

SYNOPSIS 

#include <stdio.h> 

int fflush( FILE ‘stream); 

int fpurge) FILE ‘stream); 

DESCRIPTION 

Thefunction ffiush forces a write of all buffered data for the given output or update stream via the stream's underlying write 
function. The open status of the stream is unaffected. 

If the stream argument is null, ffiush flushes all open output streams (Does this happen under Linux?) 

Thefunction fpurge erases any input or output buffered in the given stream. For output streams thisdiscards any unwritten 
output. For input streams thisdiscards any input read from the underlying object but not yet obtained via getc(3); this 
includes any text pushed back via ungetc. 

RETURN VALUES 

Upon successful completion, 0 is returned. Otherwise, eof isreturned, and the global variable errno isset to indicate the 
error. 

ERRORS 

ebadf Stream is not an open stream, or, in the case of ffiush, not a stream open for writing. 

Thefunction ffiush may also fail and set errno for any of the errors specified for the routine write(2). 



fgetgrent 


BUGS 

Linux may not support fpurge. 

SEE ALSO 

write(2), fopen(3), fclose(3), setbuf(3) 

STANDARDS 

The ffiush function conformsto AN SI C3.159-1989 ("AN SI C"). 

BSD M an Page, 29 N ovember 1993 

ffs 

ffs— Finds first bit set in a word 

SYNOPSIS 

#include <string.h> 
int ffs(int i ); 

DESCRIPTION 

Thetfso function returns the position of the first bit set in the word i. The least significant bit is position 1, and the most 
significant position 32. 

RETURN VALUE 

Theffso function returns the position of the first bit set, or null if no bits are set. 

CONFORMSTO 

BSD 4.3 

GNU, 13 April 1993 


fgetgrent 

fgetgrent— G dts group file entry 

SYNOPSIS 

#include <grp.h> 

#include <stdio.h> 

#include <sys/types.h> 

struct group *fgetgrent(FILE ‘stream); 

DESCRIPTION 

The fgetgrento function returns a pointer to a structure containing the group information from thefilestr earn. The first 
time it is cal led it returns the first entry; thereafter, it returns successive entries. Thefilest r eam must have the same format as 
/etc/group. 

Thegroupstructureisdefined in <grp.h>asfollows 

struct group { 

char *gr_name; /* group name »/ 

char *gr_passwd; /* group password */ 

gid_t gr_gid; /* group id */ 

char “grjnem; /* group members */ 
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RETURN VALUE 

T he fgetgrent( (function returns the group information structure or null if there are no more entries or an error occurs. 

ERRORS 

enomem Insufficient memory to allocate group information structure. 

C0NF0RMST0 

SVID 3 


SEE ALSO 

getgrnam(3), getgrgid(3), getgrent(3), setgrent(3), endgrent(3) 


GNU, 4 April 1993 


fgetpwent 

fgetpwent— G dts password file entry 

SYNOPSIS 

#include <pwd.h> 

//include <stdio.h> 

#include <sys/types.h> 

struct passwd ‘fgetpwent(FILE ‘stream);' 

DESCRIPTION 

The fgetpwento function returns a pointer to a structure containing the broken-out fields of a line in the files t ream. The 
first time it iscalled it returns the first entry; thereafter, it returns successive entries Thefiles t ream must have the same 
format as /etc/passwd. 

The pass wd structure is defined in <pwd.h> asfollows: 
struct passwd { 

char *pw_passwd; / 

uid_t pw_uid; / 

gid_t pw_gid; / 

char *pw_gecos; / 

char *pw_shell; / 

}; 

RETURN VALUE 

The fgetpwento function returns the passwd structure, or null if there are no more entries or an error occurs. 

ERRORS 

enomem Insufficient memory to allocate passwd structure 

FILES 

/etc/passwd password databasefile 

C0NF0RMST0 

SVID 3 


home directory */ 
shell program */ 
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SEE ALSO 

getpwnam(3), getpwuid(3), getpwent(3), setpwent(3), endpwent(3), getpw(3), putpwent( 3), passwd(5) 

GNU, 17 May 1996 


floor 

floor— Largest integral value not greater than x 

SYNOPSIS 

#include <math.h> 
double floor(double *); 

DESCRIPTION 

The fioor() function rounds* downward to the nearest integer, returning that value as a double 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

abs(3), fabs(3), cell(3), rlnt(3) 

6Junel993 


fmod 

fmod— Floating-point remainder function 

SYNOPSIS 

#include <math.h> 

double fmod(double x, double y); 

DESCRIPTION 

Themodfo function computes the remainder of dividing* by y. The return value is x-n*y, where n is the quotient of x/y, 
rounded toward 0 to an integer. 

RETURN VALUE 

The fmod() function returns the remainder unless y isO, in which case the function fails and errno issdt. 

ERRORS 

edom The denominator y isO. 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

drem(3) 

6Junel993 
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f match— M atches filename or pathname 

SYNOPSIS 



DESCRIPTION 

fnmatcho checks thes t rings argument and checks whether it matches thepat t er n argument, which is a shell wildcard 
pattern. 

Thef i ags argument modifies the behavior; it is the bitwise or of zero or more of the following flags: 
fnm_noescape If thisflag is set, treat backslash as an ordinary character instead of as an escape character. 

fnm_pathname If thisflag isset, match a slash in stri ng only with a slash in pattern and not, for example, with 

an - sequence containing a slash. 

fnm_period If this flag isset, a leading period in stri ng has to be matched exactly by a period in pattern. A 

period is considered to be leading if it isthefirst character in stri ng, or if both fnm_pathname is 
set and the period immediately follows a si ash. 

RETURN VALUE 

Zero if stri ng matches pat tern, fnm_nomatch if there is no match, or another value if there is an error. 

C0NF0RMST0 

Proposed POSIX.2 

BUGS 

POSIX.2 isnotydt an approved standard; the information in this man page is subject to change 

SEE ALSO 

sh(1), glob(3), glob(7) 

GNU, 19 April 1993 


f open, f dopen, f reopen 

fopen, fdopen, freopen- Stream open functions 

SYNOPSIS 



DESCRIPTION 

The fopen function opens the file whose name is the string pointed to by path and associates a stream with it. 

The argument mode points to a string beginning with one of the following sequences (additional characters may follow these 
sequences): 



Open text file for reading. The stream is positioned at the beginning of thefile. 
Open for reading and writing. The stream is positioned at the beginning of the file 
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w T runcatefile to zero length or create a text file for writing. The stream is positioned at the 

beginning of the file 

w+ Open for reading and writing. Thefile is created if it does not exist; otherwise it is truncated. 

The stream is positioned at the begi nni ng of the file. 

a Open for writing. Thefile iscreated if it does not exist. The stream is positioned at the end of 

thefile. 

a+ 0 pen for readi ng and writing. T he fi le is created if it does not exist. T he stream is positioned at 

the end of thefile. 

The mode string can also include the letter b either as a third character or as a character between the characters in any of the 
two-character strings described previously. This is strictly for compatibility with AN SI C 3.159-1989 (AN SI C) and has no 
effect; the b is ignored. 

Any created files will have mode s_irusr | s_iwusr j s_irgrp ] s_iwgrp | s_iroth | s_iwoth (0666), as modified by the process's 
mask value. (See mask(2).) 

Reads and writes may be intermixed on read/write streams in any order. N otethat AN SI C requires that a file positioning 
function intervene between output and input, unless an input operation encounters end-of-file. (If thiscondition isnot met, 
then a read is allowed to return the result of writes other than the most recent.) Therefore it isgood practice (and indeed 
sometimes necessary under Linux) to put an tseek or tgetpos operation between write and read operations on such a stream. 
This operation may bean apparent no-op (as in f seek (..., gl, seek_cur>) called for its synchronizing side effect. 

The fdopen function associates a stream with the existing file descriptor, mdes. The mode of the stream must be compatible 
with the mode of the file descriptor. T he file descriptor is not duplicated. 

T he f reopen function opensthefile whose name isthe string pointed to by pat h and associates the stream pointed to by 
stream with it. The original stream (if it exists) isdosed. The mode argument is used just as in thefopen function. The 
primary use of the f reopen function is to change thefile associated with a standard text stream (stderr, stdin, orstdout). 

RETURN VALUES 

On successful completion, fopen, fdopen, and f reopen return a file pointer. Otherwise null is returned, and the global 
variable errno is set to indicate the error. 

ERRORS 

einval The mode provided to fopen, fdopen, or f reopen was invalid. 

T he fopen, fdopen, and freopen functions may also fai I and set errno for any of the errors specified for the routine maiioc(3). 
Thefopen function may also fail and set errno for any of the errors specified for the routine open(2). 

T he fdopen function may also fail and sdt errno for any of the errors specified for the routine fcnti(2). 

T he f reopen function may also fai I and set errno for any of the errors specified for the routines open(2), f ciose(3) and 
fflush(3). 

SEE ALSO 

open(2), fclose(3) 

STANDARDS 

Thefopen and f reopen functions conform to AN SI C 3.159-1989 (AN SI C). The fdopen function conforms to IEEE 
Stdl003.1-1988 (POSIX.1). 

BSD M an Page, 13 D ecember 1995 


fpathconf,pathconf 

fpathconf, pathconf—Get configuration values for files 
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SYNOPSIS 

ffinclude <unistd.h> 

long fpathconf(int f i I e de s, intn a me); 

long pathconf(char ‘path, Int name); 


DESCRIPTION 


fpathconf o gets a value for the configuration option name for the open fi le descriptor f i i edes. 
pathconf () gets a value for configuration option n a me for the filename path. 

The corresponding macros defined in <untstd.h> are the minimum values; if an application wants to take advantage of values 
that may change a call to fpathconf o or pathconf o can be made, which may yield more liberal results. 


Setting name equal to one of the following constants returns thefollowing configuration options: 


_PC_LINK_MAX 
_PC_MAX_CANON 
_PC_MAX_INPUT 
_PC_NAME_MAX 
_PC PATH_MAX 
_PC_PIPE_BUF 
_PC_CHOWN_RESTRICTED 

_PC_NO_TRUNC 

_PC_VDISABLE 


Returns the maxi mum number of links to the file. If fi i edes or path refers to a directory, the 
value applies to the whole directory. The corresponding macro is_POSix_LiNK_MAx. 

Returns the maxi mum length of a formatted input line, where fi i edes or path must refer to a 
terminal. The corresponding macro is_POSixjiAx_CANON. 

Returnsthe maximum length of an input line wherefi i edes or path must refer to a terminal. 
The corresponding macro is_POSix_MAx_iNPUT. 

Returnsthe maxi mum length of a filename in the directory path or f iiedes the process is 
allowed to create. The corresponding macro is_POSix_MAx_. 

Returnsthe maximum length of a relative path name when path or f i i edes isthe current 
working directory. The corresponding macro is_POSix_PATH_MAx. 

Returns the size of the pipe buffer, wherefi i edes must refer to a pipe or FIFO, and path must 
refer to a FIFO. The corresponding macro is_POSix_piPE_BUF. 

Returns nonzero ifthechom(2) call maynotbeused onthisfile If f i i edes or pa t h refers to a 
directory, this applies to all files in that directory. The corresponding macro is 

_POSIX_CHOWN_RESTRICTED. 

Returns nonzero if accessing filenames longer than _posix_namejiax generates an error. The 
corresponding macro is_POsix_NO_TRUNC. 

Returns nonzero if special character processing can be disabled, where f i edes or pat h must 
refer to a terminal. 


RETURN VALUE 

The limit is returned, if oneexists. Ifthesystem does not have a limit for the requested resource -i is returned, and errno is 
unchanged. If there is an error, -i is returned, and errno issetto reflect the nature of the error. 

C0NF0RMST0 

POSIX.1. Files with name lengths longer than the value returned for name equal to _pc_name_max may exist in the given 
directory. 

Some returned values may be huge; they are not suitable for allocating memory. 

SEE ALSO 

getconf(l), statfs(2), open(2), sysconf(3) 

GNU, 4 April 1993 


tread, fwrite 

tread, fwrite- Binary stream input/output 



fgetpos, fseek, fsdpos ftdl, rewind 




SYNOPSIS 

#include <stdio.h> 

size_t fread(void *ptr, size_t size, size_t nmemb ,FILE*st ream); 
size_t fwrite(void *pt r , size_t size, size_t nmemb,FILE*strearn); 

DESCRIPTION 

The function fread reads nmemb elements of data, each size bytes long, from the stream pointed to by stream, storing them at 
the location given by pt r. 

The function fwrite writes nmemb elements of data, each size bytes long, to the stream pointed to by stream, obtaining them 
from the location given by pt r. 

RETURN VALUES 

fread and fwrite return the number of items successfully read or written (that is, not the number of characters). If an error 
occurs, or the end-of-file is reached, the return value is a short item count (or 0). 

fread does not distinguish between end-of-file and error, and callers must use feof(3) and ferror(3) to determine which 
occurred. 

SEE ALSO 

feof(3), ferror(3), read(2), write(2) 

STANDARDS 

The functions fread and fwrite conform to AN SI C3.159-1989 ("ANSI C"). 

BSD Man Page, 17 May 1996 


frexp 

frexp— Converts floating-point number to fractional and integral components 

SYNOPSIS 

#include <math.h> 

double frexp(double *, int *exp); 

DESCRIPTION 

Thefrexpo function is used to split the number x into a normalized fraction and an exponent that is stored in exp. 

RETURN VALUE 

Thefrexpo function rdturnsthe normalized fraction. If the argument x is not 0, the normalized fraction isx timesapower 
of 2, and isalwaysin the ranged (inclusive) to 1 (exclusive). If x is0, the normalized fraction isO, and 0 isstored in exp. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

ldexp(3), modf(3) 

GNU, 6Junel993 


fgetpos,fseek,fsetpos,ftell, rewind 

fgetpos, fseek, fsetpos, fteii, rewind— Reposition a stream 
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SYNOPSIS 

#include <stdio.h> 

int fseek(FILE ‘stream, longo ffset , int whence); 

long ftell(FILE ‘stream); 

void rewind(FILE ‘stream); 

int fgetpos(FILE ‘stream, fpos_t *pos); 

int fsetpos(FILE ‘stream, fpos_t *p os); 

DESCRIPTION 

T he t seek function sdts thefile position indicator for the stream pointed to by stream. The new position, measured in bytes, 
is obtained by adding offset bytes to the position specified by whence. If whence issetto seek_set, seek_cur, or seek_end, the 
offset is relative to the start of thefile, the current position indicator, or end-of-file, respectively. A successful call to the f seek 
function clears the end-of-file indicator for the stream and undoes any effects of the ungetc(3) function on the same stream. 

T he f ten function obtains the current value of the file position indicator for the stream pointed to by stream. 

The rewind function sets the file position indicator for the stream pointed to by streamto the beginning of thefile. Itis 
equivalent to 

(void)fseek(stream, 0L, SEEK_SET); 

except that the error indicator for the stream is also cleared. (See ciearerr(3).) 

Thefgetpos and fsetpos functions are alternate interfaces equivalent to fteii and fseek (with whence set to seek_set), setting 
and storing the current value of thefileoffset into or from the object referenced by pos . On some non-UN IX systems, an 
f pos_t object may be a complex object, and these routines might be the only way to portably reposition a text stream. 

RETURN VALUES 

The rewind function returns no value. U pon successful completion, fgetpos, fseek, and fsetpos return 0, and fteii returns 
the current offset. Otherwise, -1 is returned, and the global variable errno issetto indicate the error. 

ERRORS 

ebadf The stream specified isnotaseekablestream. 

einval The whence argument to fseek was not seek_set, seek_end, or seek_cur. 

The function fgetpos, fseek, fsetpos, and fteii might also fail and set errno for any of the errors specified for the routines 
fflush(3), fstat(2), lseek(2), and malloc(3). 

SEE ALSO 

lseek(2) 

STANDARDS 

Thefgetpos, fsetpos, fseek, fteii, and rewind functions conform to AN SI C 3.159-1989 (AN SI C). 

BSD M an Page, 29 N ovember 1993 


f time 

ftime— Returns date and time 

SYNOPSIS 

#include <sys/timeb.h> 
int ftime(struct timeb *tp); 
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DESCRIPTION 

Return current date and time in tp, which isdeclared asfollows 

struct timeb { 

unsigned short millitm; 
short timezone; 
short dstflag; 


RETURN VALUE 

This function always returns 0. 

NOTES 

Under Linux, thisfunction is implemented in a compatibility library instead of in the kernel. 

C0NF0RMST0 

Version 7, BSD 4.3 

Under BSD 4.3, thiscall isobsoleted by gettimeofday(2). 

SEE ALSO 

time(2) 

Linux, 24 July 1993 


ftok 

ftok— Converts a pathname and a project identifier to a System V I PC key 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

key_t ftok (char ‘pathname, char pr oj ); 

DESCRIPTION 

Thefunction converts the pathname of an existing accessible file and a project identifier into a key_t type System V I PC key. 

RETURN VALUE 

On success, the return value will be the converted key_t value; otherwise it will be - 1 , with errno indicating the error as for 
the stat(2) system call. 

BUGS 

The generated key_t value is obtained by stating the disk file corresponding to pathname in order to get its i-node number 
and the minor device number of the filesystem on which the disk file resides, then by combining the 8-bit pro] value along 
with the lower 16 bits of the inode number with the 8 bits of the minor device number. The algorithm does not guarantee a 
unique key value. In fact, 

■ Two different names linking to the same file produce the same key values 

■ Using the lower 16 bits of the i-node number gives some chance (although usually small) to have the same key values 
for filenames referring to different inodes 

■ Not discriminating among major device numbers gives some chance of collision (also usually small) for systems with 
multi pie disk controllers 
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SEE ALSO 

ipc(5), msgget(2), semget(2), shmget(2), stat(2) 


Linux 0.99.13,1 November 1993 


ftw 

ftw— File tree walk 

SYNOPSIS 

#include <ftw.h> 

int ftw(const char ‘directory, 

int(*f uncpt r )(const char ‘file, struct stat *sb , int fIag ), int depth); 

DESCRIPTION 

ftw () walks through the directory tree, starting from the indicated di rectory. For each found entry in the tree, it calls f uncpt r 
with thefull pathname of the entry relative to di r ect or y , a pointer to the stat(2) structure for the entry and an int whose 
value will beoneof thefollowing: 

ftw_f Item is a normal file 

ftw_d Item is a directory 

ftw_ns Thestatfailedontheitem 

ftw_dnr Item is a directory which can't be read 

Warning: Anything other than directories, such as symbolic links, gets the ftw_f tag. 

ftw() recursively calls itself for traversing found directories. T o avoid using up all a program'sfiledescriptors, depth specifies 
the number of simultaneous open directories. When the depth isexceeded, ft»o will become slower because directories have 
to be closed and reopened. 

To stop the tree walk, f uncpt r returns a nonzero value; this value will become the return valueofftp(). Otherwise, ftw() will 
continue until it has traversed the entire tree (in which case it will return 0), or until it hits an error such asamaiioc(3) 
failure, in which case it will return -1. 

Because ftp 0 uses dynamic data structures, the only safe way to exit a tree walk is to return a nonzero value. To handle 
interrupts, for example, mark that the interrupt occurred and return a nonzero value- don't use iongjmp(3) unless the 
program is going to terminate. 

SEE ALSO 

stat(2) 

Linux, 18 July 1993 


gcvt 

gcvt— Converts a floating-point number to a string 

SYNOPSIS 

#include <stdlib.h> 

char *gcvt(double number, size_t ndigit, char *b uf); 

DESCRIPTION 

Thegcvto function converts number to a minimal-length, NULL-terminated ASCII string and storesthe result in buf . It 
produces ndi gi t significant digits in either printfo F format or E format. 




gdtdirentries 


RETURN VALUE 

Thegcvto function returns the address of the string pointed to by buf. 

SEE ALSO 

ecvt(3), fcvt(3), sprintf(3) 

29 March 1993 


getcwd, get_cunnent_dir_name, getwd 

getcwd, get_current_dir_name, getwd— Get current working directory 

SYNOPSIS 

#include <unistd.h> 
char *getcwd(char *buf , size_t size); 
char *get_current_working_dir_name(void); 
char *getwd(char *buf ); 

DESCRIPTION 

The getcwd o function copies the absolute pathname of the current working directory to the array pointed to by buf , which is 
of length si ze. 

If the current absolute pathname would require a buffer longer than size elements, null is returned, and errno isset to 
erange; an application should check for thiserror, and allocate a larger buffer if necessary. 

As an extension to the PO SI X .1 standard, getcwd () allocates the buffer dynamically using maiioc o if buf is null on cal I . I n 
thiscase, theallocated buffer hasthelength size unless s i ze isless than 0, when buf i s all ocated as large as necessary. 11 is 
possi ble (and, indeed, advisable) to free the buffers if they have been obtained this way. 

get_current_dir_name, which isonly prototyped if_ use_gnu isdefined, will maiioc(3) an array big enough to hold the 

current directory name. If the environment variable pwd isset, and its value is correct, that value will be returned. 

getwd, which is only prototyped if_ use_bsd isdefined, will notmaiioc(3) any memory. The buf argument should be a 

pointer to an array at least path_max bytes long, getwd returns only the first path_max bytes of the actual pathname. 

RETURN VALUE 

null on failure (for example, if the current directory is not readable), with errno set accordingly, and buf on success 

C0NF0RMST0 

POSIX.1 


SEE ALSO 

chdir(2), free(3), malloc(3). 


GNU, 21 July 1993 


getdirentries 

getdirentries-G ets directory entries in a filesystem-independent format 

SYNOPSIS 

#define _USE_BSD or #define _USE_MISC 
ffinclude <dirent.h> 
ssize_t getdirentries 


>(int f d, char *buf , size_t nbytes ,offt 
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DESCRIPTION 

Thisfunction reads directory entriesfrom thedirectory specified by f d into buf . At most, ibytes are read. Reading starts at 
offset *tasep, and *basep is updated with the new position after reading. 

RETURN VALUE 

getdirentries returns the number of bytes read, or 0 when at the end of thedirectory. If an error occurs, -1 is returned, and 
errno isset appropriately. 

ERRORS 

Seethe Linux library source code for details 

SEE ALSO 

open(2), lseek(2) 

BSD/M ISC, 22 July 1993 


getenv 

getenv-Getsan environment variable 

SYNOPSIS 

#include <stdlib.h> 

char *getenv(const char ‘name); 

DESCRIPTION 

The getenv) ) function searches the environment list for a string that matches the string pointed to byname. The strings are of 
theform name=*al ue. 

RETURN VALUE 

The getenv) ) function returns a pointer to the value in the environment, or null if there is no match. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

putenv(3), setenv(3), unsetenv(3) 

GNU, 3 April 1993 


getgrent,setgrent,endgnent 

getgrent, setgrent, endgrent— Get group file entry 

SYNOPSIS 

#include <grp.h> 

#include <sys/types.h> 
struct group ‘getgrent(void); 
void setgrent(void); 
void endgrent(void); 
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DESCRIPTION 

T hegetgrento function returns a pointer to a structure containing the group information from /etc/group. Thefirst time it 
is called it returns the first entry; thereafter, it returns successive entries. 

The setgrent () function rewinds thefile pointer to the beginning of the /etc/group file. 

Theendgrento function doses the /etc/group file 
Thegroupstructureisdefined in <grp.h>asfollows 

struct group { 

char *gr_name; /* group name */ 

char *gr_passwd; /* group password */ 

gid_t gr_gid; /* group id */ 

char **gr_mem; /* group members */ 

}; 

RETURN VALUE 

T he getgrent( (function returns the group information structure, or null if there are no more entries or an error occurs 

ERRORS 

enomem Insufficient memory to allocate group information structure. 

FILES 

/etc/group group database file 

C0NF0RMST0 

SVID 3, BSD 4.3 

SEE ALSO 

fgetgrent(3), getgrnam(3), getgrgid(3) 

GNU, 4 April 1993 


getgrnam,getgrgid 

getgrnam, getgrgid— Gdt group file entry 

SYNOPSIS 

#include <grp.h> 

#include <sys/types.h> 

struct group *getgrnam(const char ‘name); 

struct group *getgrgid(gid_t gi d); 

DESCRIPTION 

The getgrnam( ) function returns a pointer to a structure containing the group information from /etc/group for the entry that 
matches the group name name. 

The getgrgid( ) function returns a pointer to a structure containing the group information from /etc/group for the entry that 
matches the group id gi d. 

Thegroupstructureisdefined in <grp.h>asfollows 

struct group { 

char *gr_name; /* group name */ 

char *gr_passwd; /* group password */ 
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gid_t gr_gid; /* group id */ 

char **gr_mem; /* group members */ 


RETURN VALUE 

The getgrnam( )and getgrgido functions return the group information structure, or null if the matching entry is not found 
or an error occurs. 

ERRORS 

enomem Insufficient memory to allocate group information structure. 

FILES 

/etc/group group database file 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3 

SEE ALSO 

fgetgrent(3), getgrent(3), setgrent(3), endgrent(3) 

GNU, 4 April 1993 


getlogin,cuserid 

getiogin, cuserid— Get username 

SYNOPSIS 

#include <unistd.h> 
char * getlogin ( void ); 

#include <stdio.h> 

char * cuserid ( char ‘string ); 

DESCRIPTION 

getlogin returnsa pointer to a string containing the nameof the user logged in on the controlling terminal of the process, or 
a null pointer if this information cannot be determined. The string isstatically allocated and might be overwritten on 
subsequent calls to thisfunction or to cuserid. 

cuserid returnsa pointer to a string containing a username associated with the effective user ID of the process Ifstri ng is 
not a null pointer, it should bean array that can hold at least L_cuserid characters; theString is returned in thisarray. 
Otherwise, a pointer to a string in a static area is returned. This string isstatically allocated and might be overwritten on 
subsequent calls to thisfunction or to getlogin. 

The macro L_cuserid is an integer constant that indicates how long an array you might need to store a username. L_cuserid is 
declared in stdio.h. 

T hese functions let your program positively identify the user who is running (cuserid) or the user who logged in this session 
(getlogin). (These can differ when setuid programs are involved.) The user cannot do anything to fool these functions 
For most purposes it is more useful to use the environment variable logname to find out who the user is. This is more flexible 
precisely because the user can set logname arbitrarily. 

ERRORS 


ENOMEM 


Insufficient memory to allocate passwd structure 
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FILES 

The /etc/passwd password database file /etc/utmp (or /var/adm/utmp, or wherever your utmp file lives these days- the proper 
location depends on your libc version) 

C0NF0RMST0 

POSIX.1. System V hasacuserid function that uses the real user ID rather than the effective user ID. Thecuserid function 
wasinduded in the 1988 version of POSIX, but was removed from the 1990 version. 

BUGS 

Unfortunately, it is often rather easy to fool getiogino. Sometimes it does not work at all, because some program messed up 
the utmp file Often, it givesonly thefirst eight characters of the login name. The user currently logged in on the controlling 
tty of your program need not be the user who started it. 

N obody knows precisely what cuserid () does; so 

■ Avoid it in portable programs 

■ Avoid it altogether 

■ Usegetpwutd (geteuido) instead, if that iswhat you meant. 

Simply, do not U3Scuserid(). 

SEE ALSO 

geteuid(2), getuid(2) 

Linux 1.2.13, 3 September 1995 

getmntent,setmntent,addmntent, endmntent, hasmntopt 

getmntent, setmntent, addmntent, endmntent, hasmntopt—Gdt filesystem descriptor file entry 

SYNOPSIS 

#include <stdio.h> 

#include <mntent.h> 

FILE *setmntent(const char *fiIep, const char ‘type); 
struct mntent ‘getmntent(FILE *filep); 
int addmntent(FILE ‘filep, const struct mntent *mnt); 
int endmntent(FILE ‘filep); 

char ‘hasmntopt(const struct mntent *mnt , const char ‘opt ); 

DESCRIPTION 

These routines are used to access the filesystem description file /etc/fstab and the mounted filesystem description file /etc/ 
mstab. 

The setmntent o function opens the filesystem description filer i i ep and returns a file pointer that can be used by 
getmntent o. The argument type isthe type of access required and can take the same values as the mode argument of fopen(3). 
The getmntent o function reads the next line from the filesystem description filer i i ep and returns a pointer to a structure 
containing the broken-out fields from a line in the file The pointer points to astatic area of memory that is overwritten by 
subsequent calls to getmntent (). 

The addmntent o function adds the mntent structure mnt to the end of the open file filep. 

The endmntent o function doses the filesystem description filet i i ep. 

The hasmntopt o function scans the mnt _opts field of the mntent structure mnt for a substring that matches opt. (See 
<mntent.h> for valid mount options) 
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T he mntent structure is defined in <mntent.h> asfollows 


struct mntent { 



*mnt_fsname; 

*mnt_type; 

mnt_freq; 
mnt_passno; 


/* name of mounted filesystem */ 
/* filesystem path prefix */ 

/* mount type (see mntent.h) */ 

/* mount options (see mntent.h) */ 
/* dump frequency in days */ 

/* pass number on parallel fsck */ 


RETURN VALUE 

Thegetmntento function returns a pointer to themntent structure or null on failure. 

Theaddmntento function returns 0 on success and i on failure. 

The endmntent () functions always returns i . 

The hasmntopt () function returnsthe address of thesubstring if amatch isfound.and null otherwise 

FILES 

/etc/fstab filesystem description file 
/etc/mtab mounted filesystem description file 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

fopen(3), fstab(5) 
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getnetent,getnetbyaddr,getnetbyname,setnetent,endnetent 

getnetent, getnetbyaddr, getnetbyname, setnetent, endnetent— Get network entry 

SYNTAX 

#include <netdb.h> 
struct netent ‘getnetent () 
struct netent *getnetbyname(name) 

struct netent *getnetbyaddr(net , type) 
void setnetent(stay open) 
void endnetent() 


DESCRIPTION 

The getnetent, getnetbyname, and getnetbyaddr subroutines each return a pointer to an object with the following structure 
containing the broken-out fields of a line in the network database /etc/networks: 


struct netent { 


int n_addrtype; 

long n_net; 


/* official name of net */ 
/* alias list */ 

/* net number type */ 

/* net number */ 






T he members of this structure are 


getopt 




The official name of the network. 

A zero-terminated list of alternate names for the network. 

The type of the network number returned: af_inet. 

The network number. Network numbers are returned in machine byte order. 

If thest ayopen flag on a setnetent subroutine is null, the network database is opened. Otherwise the setnetent has the effect 
of rewindi ng the network database Theendnetent may be called to close the network database when processing is complete. 
Thegetnetent subroutine simply reads the next line whereas getnetbyname and getnetbyaddr search until a matching name or 
net number isfound (or until eof is encountered). The type must be af_inet. Thegetnetent subroutine keeps a pointer in 
the database, allowing successive calls to be used to search the entire file. 

A call to setnetent must be made before a while loop using getnetent to perform initialization, and an endnetent must be 
used after the loop. Both getnetbyname and getnetbyaddr makecallsto setnetent and endnetent. 

FILES 

/etc/networks 

DIAGNOSTICS 

N ull pointer ( 0 ) returned on eof or error. 

SEE ALSO 

networks(5), RFC 1101 

HISTORY 

Thegetnetent)), getnetbyaddr)), getnetbyname)), setnetent)), and endnetent) ) functions appeared in 4.2BSD . 

BUGS 

The data space used by these functions is static; if future use requires the data, it should be copied before any subsequent calls 
to these functions overwrite it. Only Internet network numbers are currently understood. Expecting network numbers to fit 
in no more than 32 bits is probably naive. 

getopt 

getopt- Parses command-lineoptions 

SYNOPSIS 

#include <unistd.h> 

int getopt(int argc, char * const argvI ] , 


n_aliases 

n_addrtype 

n_net 


extern int optind, opt er r , opt opt ; 

#include <getopt.h> 

int getopt_long(int argc, char * const a rgv [| , 


const char ‘optstring, 

const struct option. yttysgo:: s , int *1 ongi rdex ); 
int getopt_long_only(int argc, char * const arg*[] , 


const struct option *U|S 


ngopts , 






Part III: L ibrary Functions 


938 


DESCRIPTION 

Thegetopto function parses the command-line arguments. Its arguments argc and argv are the argument count and array as 
passed tothemaino function on program invocation. An element of argv that starts with - (and is not exactly - or--) isan 
option element. The characters of this element (aside from the initial -) areoption characters If getopto iscalled repeatedly, 
it returns successively each of the option characters from each of the option elements 

If getopto finds another option character, it returns that character, updating the external variable opti nd and a static variable 
next char so that the next call to getopto can resume the scan with the following option character or argv element. 

If there are no more option characters getopto returns eof. Then optind isthe index in argv of thefirst argv element that is 
not an option. 

optstri ng isa string containing the legitimate option characters If such a character is followed by a colon, the option 
requires an argument, so getopt placesa pointer to thefollowing text in thesame argv element, or the text of the following 
argv element, in opt ar g . T wo colons mean an option takes an optional arg; if there is text in the current argv element, it is 
returned in opt arg; otherwise, opt arg issetto 0 . 

By default, getargs () permutes the contents of a r g v as it scans so that eventually all the non-options are at the end. T wo 
other modes are also implemented. If thefirst character of optstring is + or theenvironment variable posixly_correct isset, 
option processing stops as soon asa non-option argument isencountered. If thefirst character of optstring is -, each non¬ 
option argv element is handled as if it were the argument of an option with character code 1. (This is used by programsthat 
were written to expect options and other argv elements in any order and that care about the ordering of the two.) The special 
argument - forces an end of option-scanning regardless of the scanning mode. 

If getopto does not recognize an option character, it prints an error message to stderr, stores the character in optopt, and 
returns?. The calling program may prevent the error message by setting opterr to 0 . 

The getopt_iong( (function works like getopt (), except that it also accepts long options, started out by two dashes. Long 
option names may be abbreviated if the abbreviation is unique or isan exact match for some defined option. A long option 
may take a parameter, oftheform--arg=paramor--arg param. 

1 ongopt s isa pointer to thefirst element of an array of struct option declared in <getopt .h>: 


as struct option { 



T he meanings of the different fields are 

name The nameof thelong option. 

has.arg no_argument (or 0) if the option does not take an argument, required_argument (or 1) if the 

option requires an argument, or optionai_argument (or 2) if the option takes an optional 
argument. 

flag Specifies how results are returned for a long option. If f 1 ag is null, getopt_iong() returns va 1. 

(For example the calling program might set v a 1 to the equivalent short option character.) 
Otherwise, getopt_iong(> returns 0, and f 1 ag pointsto a variablethat isset to vai iftheoption 
is found, but left unchanged iftheoption is not found, 
v a 1 The value to return or to load into the variable pointed to by f 1 a g. 

The last element of the array has to be filled with zeroes. 

If 1 ongi ndex is not null, it pointsto a variable that issdt to the index of the long option relative to 1 ongopt s. 
getopt_iong_oniy () is like getopt_iong< ), but - aswell as --can indicatea long option. If an option that starts with - (not--) 
doesn't match a long option but does match a short option, it is parsed asa short option instead. 




getopt 


939 


RETURN VALUE 

The getopt ((function returns the option character if the option was found successfully,: if there was a missing parameter for 
one of the options, ? for an unknown option character, or eof for the end of the option list. 

getopt_iong() and getopt_iong_oniy() also return theoption character when a short option is recognized. For a long option, 
they return vai iff i ag isNULL, and 0 otherwise Error and eof returns are the same as for getopt 0 , plus? for an ambiguous 
match or an extraneous parameter. 

ENVIRONMENT VARIABLES 

posixly_correct If thisisset, option processingstopsassoon asanon-option argumentisencountered. 

EXAMPLE 

The following example program, from the source code illustrates the use of getopt_iong() with most of its features; 

((include <stdio.h> 


main (ar gc, ar gv) 


char **ar gv; 


int di gi t_ 0 ptind = 0; 
while (1) 

{ 

int this_optionoptind = optind ? optind ; 1; 

static struct option Iongoptions[] % 

{ 

{"add", 1, 0, 0}, 

{"append", 0, 0, 0 }, 

{"delete", 1, 0, 0}, 

{"verbose", 0 , 0, 0}, 

{"create", 1, 0, 'c'}, 

{"file", 1, 0 , 0g, f0, 0, 0, 0} 

}; 

c = getopt_long (argc, argv, "abc:d:012", 

Iongopti ons, &option_index); 


switch(c) 


printf ("option %s", Iong options[ option_i ndex].name); 
if (opt arg) 

printf (" with arg %s", optarg); 
printf ("\n"(; 


if (di gi t_opti nd != 0 && di gi topti nd != thi s_opti onopti nd) 
printf ("digits occur in two different argv-elements.\n"); 
{li g i topti* t hi s_0pt i 0n_0pt i nd; 
printf ("option %c\n", c); 


printf ("option a\n"(; 
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printf ("option b\n"); 


printf ("option c with value '%s 1 \n", optarg); 


printf ("option d with value '%s' \n", optarg); 



default: 

printf ("?? getopt returned character code 0%o ??\n", c); 


if (opti ifi: '% argc) 

{ 

printf ("non-option ARGV-elements: "); 
printf ("%s ", argv[opti nd++] ); 


exit (0); 

} 

BUGS 

This man page is confusing. 

C0NF0RMST0 

getopto: POSIX.1, provided the environment variable posixly_correct issdt. Otherwise the elements of argv aren't 

really const, because they gdt permuted. They’re set const in the prototype to be compatible with other 
systems 

GNU, 30 August 1995 

getpass 

getpass-Gets a password 

SYNOPSIS 

#include <pwd.h> 

#include <unistd.h> 

char ‘getpass( const char * prompt ); 

DESCRIPTION 

The getpass function displaysa prompt to, and reads in, a password from, /dev/tty. If thisfile is not accessible, getpass 
displays the prompt on the standard error output and reads from the standard input. 

The password may be up to _password_len (currently 128) characters in length. Any additional characters and the terminat¬ 
ing newlinecharacter are discarded. (This might be different in Linux.) 
getpass turns off character echoing while reading the password. 

RETURN VALUES 

getpass returns a pointer to the null-terminated password. 




gdtprotoent, getprotobyname gdtprotobynumber, 93tprotoent, endprotoent 




FILES 

/dev/tty 

SEE ALSO 

crypt(3) 

HISTORY 

A getpass function appeared in Version 7 AT&T UN IX. 

BUGS 

The getpass function leaves its result in an internal static object and returnsa pointer to that object. Subsequent calls to 
getpass will modify the same object. 

Thecalling process should zero the password as soon as possible to avoid leaving the cleartext password visible in the 
process's address space. 

BSD Man Page29 November 1993 

getprotoent, getprotobyname, getprotobynumber,setprotoent, 
endprotoent 

getprotoent, getprotobyname, getprotobynumber, setprotoent, endprotoent— Get protocol entry 

SYNOPSIS 

#include <netdb.h> 

struct protoent *getprotoent(void); 

struct protoent *getprotobyname(const char *na me); 

struct protoent *getprotobynumber(int proto); 

void setprotoent(int stayopen); 

void endprotoent(void); 

DESCRIPTION 

The getprotoent o function readsthenext line from thefile /etc/protocois and returns a structure protoent containing the 
broken-out fields from the line The /etc/protocois file isopened if necessary. 

The getprotobyname () function returns a pr ot oent structure for the li ne from /etc/protocois that matches the protocol name 


Thegetprotobynumber() function returns a pr ot oent structure for the line that matches the protocol number number. 
The setprotoent/) function opens and rewinds the /etc/protocois file If stay open istrue (i), thefile will not be closed 
between calls to getprotobyname () Or getprotobynumber)). 

The endprotoent)) function Closes /etc/protocols. 

The protoent structure is defined in <netdb.h> as follows: 
struct protoent { 

char *p_name; /* official protocol name */ 

char **p_aliases; /* alias list */ 

int p_proto; /* protocol number */ 
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T he members of the protoent structure are 

p_name T he official name of the protocol. 

p_aiiases A zero-terminated list of alternative names for the protocol. 

p_proto The protocol number. 

RETURN VALUE 

Thegetprotoento, getprotobynameo, and getprotobynumbero functions return the protoent structure, or aNULL pointer if an 
error occurs or the end of the file is reached. 

FILES 

/etc/protocois protocol database file 

C0NF0RMST0 

BSD 4.3 



SEE ALSO 

getservent(3), getnetent(3), protocols(5) 


BSD, 24 April 1993 


getpw 

getpw— Reconstructs password line entry 

SYNOPSIS 

//include <pwd.h> 

#include <sys/types.h> 

int getpw(uid_t u i d , char *buf ); 


DESCRIPTION 

Thegetpwo function reconstructs the password line entry for the given user U ID ui d in the buffer but. The returned buffer 

containsalineof format 

name:passwd:uid:gid:gecos:dir:shell 

The passwd structure is defined in <pwd.h> as follows: 



/*username*/ 


/* real name */ 

/* home directory */ 
/* shell program */ 


RETURN VALUE 

T he getpw( (function returns a on success, or -i if an error occurs. 

ERRORS 


ENOMEM 


Insufficient memory to allocate passwd structure 
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FILES 

/etc/passwd Password databasefile 

SEE ALSO 

fgetpwent(3), getpwent(3), setpwent(3), endpwent(3), getpwnam(3), getpwuid(3), putpwent(3), passwd(5) 

GNU, 27 May 1996 


getpwent, setpwent, endpwent 

getpwent, setpwent, endpwent— gdt password file entry 

SYNOPSIS 

#include <pwd.h> 

#include <sys/types.h> 
struct passwd *getpwent(void); 
void setpwent(void); 
void endpwent(void); 

DESCRIPTION 

T he getpwent () function returns a pointer to a structure containing the broken-out fields of a line from /etc/passwd. T he 
first time it is called it returns thefirst entry; thereafter, it returns successive entries 
The setpwent o function rewinds thefile pointer to the beginning of the /etc/passwd file 
Theendpwento function dosesthe /etc/passwd file. 

The passwd structure isdefined in <pwd.h> as follows: 


struct passwd { 

char *pw_passwd; 

uid_t pw_uid; 

gid_t pw_gid; 

char *pw_gecos; 

char *pw_shell; 


/* home directory */ 
/* shell program */ 


RETURN VALUE 

The getpwent ((function returns the passwd structure, or null if there are no more entries or an error occurs. 

ERRORS 

enomem I nsufficient memory to allocate passwd structure 

FILES 

/etc/passwd Password databasefile 

C0NF0RMST0 

SVID 3, BSD 4.3 

SEE ALSO 

fgetpwent(3), getpwnam(3), getpwuid(3), getpw(3), putpwent(3), passwd(5). 


GNU, 27 May 1996 
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getpwnam, getpwuid 

getpwnam, getpwuid— Gdt password file entry 

SYNOPSIS 

#include <pwd.h> 

#include <sys/types.h> 

struct passwd *getpwnam(const char * name); 

struct passwd ‘getpwuid(uid_t uid); 


DESCRIPTION 

The getpwnam o function returns a pointer to a structure containing the broken out fields of alinefrom /etc/passwd for the 
entry that matches the username n a me. 

The getpwuid o function returns a pointer to a structure containing the broken-out fields of alinefrom /etc/passwd for the 
entry that matches the user UID u i d . 

The passwd structure is defined in <pwd.h> as follows: 


struct passwd { 

char *pw_passwd; 

uid_t pw_uid; 

gid_t pw_gid; 

char *pw_gecos; 

char *pw_shell; 


/* home directory */ 
/* shell program */ 


RETURN VALUE 

The getpwnam oand getpwuid o functions return the passwd structure or null if the matching entry isnot found or an error 
occurs. 

ERRORS 

enomem Insufficient memory to allocate passwd structure 

FILES 

/etc/passwd Password databasefile 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3 

SEE ALSO 

fgetpwent(3), getpwent(3), setpwent(3), endpwent(3), getpw(3), putpwent(3), passwd(5) 

GNU, 27 May 1996 


fgetc, f gets, getc, getchar, gets, ungetc 

fgetc, tgets, getc, getchar, gets, ungetc— Input of characters and strings 


SYNOPSIS 

//include <stdio.h> 

int fgetc(FILE ‘stream); 

char *fgets(char *s,int size 


, FILE ‘stream); 
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int getc(FILE ‘stream); 

int getchar(void); 

char ‘gets(char *s); 

int ungetc(int c, FILE ‘stream); 

DESCRIPTION 

f getc () reads the next character from s t r e a m and returns it as an unsigned char cast to an int, or eof on end of file or error, 
getco is equivalent to tgetco except that it can be implemented as a macro that evaluates s t r eam more than once 
getcharo is equivalent to getc(s t din). 

gets) (reads a line from stdin into the buffer pointed to by s until either a terminating newline or EOF, which it replaces 
with \0. N o check for buffer overrun is performed (see the following "Bus" section). 

fgetso reads in at most one less than n characters from stream and stores them into the buffer pointed to by s. Reading stops 
after an eof ora newline If a newline is read, it is stored into the buffer. \e isstored after the last character in the buffer, 
ungetco pushesc back to st r ea m, cast to unsigned char, where it isavailablefor subsequent read operations. Pushed-back 
characters will be returned in reverse order; only one pushback is guaranteed. 

Calls to the functions described here can be mixed with each other and with calls to other input functions from the stdio 
library for the same input stream. 

RETURN VALUES 

tgetco, getco, and getcharo return the character read as an unsigned char cast to an int, or eof on end of file or error, 
getso and fgetso return s on success, and null on error or when end offileoccurswhileno characters have been read, 
ungetco returnsc on success, or eof on error. 

C0NF0RMST0 

ANSI—C, POSIX.1 

BUGS 

Becauseit is impossible to tell without knowing the data in advance how many characters getso will read, and because 
getso will continue to store characters past the end of the buffer, it is extremely dangerous to use. It has been used to break 
computer security. Use fgetso instead. 

It is not advisable to mix calls to input functions from the stdio library with low-level callsto reado for thefile descriptor 
associated with the input stream; the results will be undefined and very probably not what you want. 

SEE ALSO 

read(2), write(2), fopen(3), fread(3), scanf(3), puts(3), fseek(3), ferror(3) 

GNU, 4 April 1993 

getservent,getservbyname,getservbyport,setservent, 
endservent 

getservent, getservbyname, getservbyport, setservent, endservent—Get Service entry 

SYNOPSIS 

#include <netdb.h> 

struct servent ‘getservent(void); 

struct servent *getservbyname(const char ‘name, const char ‘proto); 
struct servent *getservbyport(int port, const char ‘proto); 
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void setservent(int stayopen ); 
void endservent(void); 

DESCRIPTION 

T he getservent ((function reads the next line from the file/etc/services and returns a structure, ser vent, containing the 
broken out fields from the line The/etc/services file isopened if necessary. 

T he getservbynamei (function returns a ser vent structure for the line from /etc/services that matches the service name using 
protocol proto. 

T he getservbyport( (function returns a s e r ven t structure for the line that matches the port por t given in network byte order 
using protocol proto. 

The setservent( (function opens and rewinds the/etc/services file. If stayopen istrue(i), the file will not be closed between 
calls to getservbynameO and getservbyport(). 

Theendservent() function Closes/etc/services. 

Theservent structu re is defined in <netdb.h> asfollows 

char *s_name; /* official service name */ 
char **s _a I i a s e s; /* alias list */ 
int sport ; /* port number */ 
char *s_proto; /* protocol to use */ 

T he members of theservent structure are: 
s. na me The official name of the service, 

s _ a i i ases A zero-terminated list of alternative names for the service, 

sport The port number for the service, given in network byteorder. 

s p r ot o The name of the protocol to use with thisservice 

RETURN VALUE 

T he getservent (), getservbyname (), and getservbyport () functions return the s e r v e n t structure or a null pointer if an error 
occurs or the end of thefile is reached. 

FILES 

/etc/services Services database file 


C0NF0RMST0 

BSD 4.3 

SEE ALSO 

getprotoent(3), getnetent(3), services(5) 


BSD, 22 April 1996 


getusershell,setusershell, endusershell 

getusershell, setusershell, endusershell- Get legal User shells 

SYNOPSIS 

#include <unistd.h> 
char *getusershell(void); 




getutent, getutid, getutline, pututline setutent, endutent, utmpname 




void setusershell(void); 
void endusershell(void); 


DESCRIPTION 

Thegetusersheiio function returns the next line from thefile /etc/sheiis, opening the file if necessary. The line should 
contain the pathnameof a valid user shell. If /etc/sheiis does not exist or is unreadable, getusersheii( ) behaves as if / bin/sh 
and /bin/csh were listed in thefile. 

The setusershell() function rewinds /etc/shells. 

The endusershell( ) function doses /etc/shells. 

RETURN VALUE 

Thegetusersheiio function rdturnsaNULL pointer on end of file 

FILES 

/etc/shells 

C0NF0RMST0 

BSD 4.3 


SEE ALSO 

shells(5) 


BSD, 4 July 1993 


getutent,getutid,getutline,pututline,setutent,endutent, 
utmpname 

getutent, getutid, getutline, pututline, setutent, endutent, utmpname— Access utmp file entries 

SYNOPSIS 

//include <utmp.h> 

struct utmp *getutent(void); 

struct utmp *getutid(struct utmp *ut); 

struct utmp *getutline(struct utmp *ut); 

void pututline(struct utmp *ut); 

void setutent(void); 

void endutent(void); 

DESCRIPTION 

utmpname o sets the name of the utmp-formatfilefor the other utmp functionsto access. If utmpnameo isnot used to set the 
filename beforetheotherfunctionsare used, they assume pathjjtmp, as defined in <paths.h>. 
setutent) ) rewinds thefile pointer to the beginning of theutmp file. It is generally a good idea to call it before any of the 
other functions. 

endutent () closes the utmp file It should be called when the user code is done accessing the fi le with the other functions, 
getutento readsa linefrom the current file position in the utmp file. It returns a pointer to a structure containing the fields 
of the line. 

getutid ((searches forward from the current file position in theutmp file based on ut . If ut ->ut_type isRUN_LVL, boot_time, 
newjtime, or old_time, getutid () will find the first entry whose ut_type field matches ut ->ut_type. If ut ->ut_type is 
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init_process, login_process, user_process, or dead_process, getutido will find the first entry whose ut_id field matches 

getutiineo searches forward from the current file position intheutmpfile. It scans entries whose ut type is user_process or 
login_process and returns the first one whose ut_iine field matchesut ->ut_iine. 

pututiine( (writes the utmp structure ut into the utmp file. It uses getutido to search for the proper place in the file to insert 
the new entry. If it cannot find an appropriate slot for ut, pututiineo will append the new entry to the end of the file. 

RETURN VALUE 

getutento, getutido, and getutiineo return a pointer to a struct utmp, which isdefined in <utmp.h>. 

FILES 

/var/run/utmp- Database of currently logged-in users 
/var/iog/wtmp— D atabaseof past user logins 

C0NF0RMST0 

XPG 2, SVID 2, Linux FSSTN D 1.2 

SEE ALSO 

utmp(5) 

Linuxlibc5.0.0, 22 M arch 1995 


getw, putw 

getw, putw— Input and output of words (ints) 

SYNOPSIS 

#include <stdio.h> 

int getw(FILE ‘stream); 

int putwfint w,FILE*strearn); 

DESCRIPTION 

getw reads a word (that is an int) from stream. It's provided for compatibility with SVID. I recommend you usetread(3) 
instead, putw writes the word # (that is, an int) to stream. It is provided for compatibility with SVID, but I recommend you 
use fwrite(3) instead. 

RETURN VALUES 

N ormally, getw returns the word read, and putw returnstheword written. 0 n error, they return eof. 

BUGS 

The value returned on error is also a legitimate data value. ferror(3) can beused to distinguish between the two cases 

C0NF0RMST0 

SVID 

SEE ALSO 

fread(3), fwrite(3), ferror(3), getc(3), putc(3) 


GNU, 16 September 1995 
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glob,globfree 

glob, globfree— Find pathnames matching a pattern; free memory from giob() 

SYNOPSIS 



glob_t *pgl ob); 

void globfree(glob_t *pgIob); 


DESCRIPTION 

ThegiobO function searches for all the pathnames matching pat tern according to the rules used by the shell (see giob(7)). 
No tilde expansion or parameter substitution is done 

The globfree o function frees the dynamically allocated storage from an earlier call to giobo. 

The results of agiobo call are stored in the structure pointed to bypgiob, which is a giob_t that is declared in <giob.h>as 



int gl_pathc; /* Count of paths matched so far */ 



int gl_flags; /* Flags for globbing */ 

} glob_t; 

Results are stored in dynamically allocated storage. 

The parameter f ags is made up of bitwise OR of zero or more the following symbolic constants, which modify the of 
behavior of giobo: 

glob_err Return on read error (because a directory does not have read permission, for example). 

glob_mark Append a slash to each path which corresponds to a directory. 

glob_nosort D on't sort the returned pathnames (they are by default). 

glob_doofs p g i o b->g i _ o f f s slots wi 11 be reserved at the beginning of the list of strings in pgi ob ->pat hv. 

glob_nocheck If no pattern matches, return the original pattern. 

glob_append Append to the results of a previous call. D o not set thisflag on the first invocation of giob(). 

glob_noescape M eta characters cannot be quoted by backslashes 

glob_period A leading period can be matched by meta characters 

If errfunc is not null, it will be called in case of an error with the arguments epath, a pointer to the path that failed, and 
eerrno, the value of emno as returned from one of the calls to opendiro, readdiro, or stat (). If errfunc returns nonzero, or 
if glob_err isset, giobo will terminate after the call to errfunc. 

Upon successful return, pgi ob ->gi _pat he containsthe number of matched pathnames and pgi ob ->gi_pathv a pointer to the 
list of matched pathnames. Thefirst pointer after the last pathname is null. 

It is possible to call giobo several times. In that case, the glob_append flag has to beset inf i ags on the second and later 
invocations 

RETURN VALUES 

On successful completion, giobo returns®. Other possible returns are 
glob_nospace For running out of memory, 

glob_abend Fora read error, and 

glob_nomatch For no found matches 
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EXAMPLES 

0 ne example of use is the following code, which simulates typing in the shell: 

Is -1 *.c c 

glob_t globbuf; 
globbuf.gl_offs = 2; 

glob(■*.<!", GL0B_D00FS, NULL, &globbuf); 

globe../*.o', GL0B_D00FS I GLOB_APPEND, NULL, iglobbuf); 

globbuf.gl_pathv[0] = "Is"; 

globbuf.gl_pathv[1] = "-1"; 

execvp("Is", &globbuf.gl_pathv[0]); 

C0NF0RMST0 

Proposed POSIX.2 

BUGS 

Thegiobofunction may fail due to failure of underlying function calls, such asmalioco or opendir(). These will store their 
error code in errno. 

POSIX.2 is not yet an approved standard; the information in this man page is subject to change 

SEE ALSO 

ls( 1), sh(l), exec(2), stat(2), malloc(3), opendir(3), readdir(3), wordexp(3), glob(7) 

GNU, 13 May 1996 

hosts_access, hosts_ctl 

hosts_access, hosts_cti— Access-control library functions 

SYNOPSIS 


//include "log_tcp.h" 



DESCRIPTION 

The routines described in this document are part of theubwrap.a library. They implement a pattern-based access-control 
language with optional shell commands that are executed when a pattern fires 

In all cases the daemon argument should specify a daemon process name (ar g*[ o] value). The client host address should bea 
valid address or fromjjnknown if the address lookup failed. The client hostname and username should be empty strings if no 
information is available, fromjjnknown if the lookup fai led, or an actual hostname or username. 

hosts_access( ) consults the access-control tables described in the hosts_access(5) manual page. hosts_access() returnso if 
access should be denied. 

hosts_cti() is a wrapper around the hosts_access() routine with a perhaps more convenient interface (although itdoesnot 
pass on enough information to support automated remote username lookups). hosts_ctio returns 0 if access should be 
denied. 
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The a 11 ow.semi ty and deny, sever i ty variables determine how accepted and rgected requests can be logged. They must be 
provided by the caller and can be modified by rules in the access-control tables. 

DIAGNOSTICS 

Problems are reported viathe sysiog daemon. 

SEE ALSO 

hosts_access(5) (format of the access control tables), hosts_options(5), optional extensions to the base language 

FILES 

/etc/hosts.access, /etc/hosts.deny access-control tables 

BUGS 

The functions described here do not make copies of their string-valued arguments. Beware of data from functions that 
overwrite their results on each call. 

hosts_access() usesthestrtok() library function. This may interfere with other code that relies on strtok(). 

AUTHOR 

W idtse V enema (wietse@wzv. win . tue. nl) 

Department of M athematicsand Computing Science 
Eindhoven U niversity of Technology 

Den Dolech 2, P.O. Box 513, 5600 M B Eindhoven, The Netherlands 

hcreate,hdestnoy, hsearch 

hcreate, hdestroy, hsearch— H ash table management 

SYNOPSIS 

#include <search.h> 

ENTRY *hsearch(ENTRY item, ACTION action); 
int hcreate(unsigned nel ); 
void hdestroy(voi d); 

DESCRIPTION 

These three functions allow the user to create a hash table that associates a key with any data. 

First, the table must be created with the function hcreateo. nei isan estimate of the number of entries in the table, 
hcreate o may adjust this value upward to improve the performance of the resulting hash table. TheGN U implementation 
of hsearch o will also enlarge thetable if it gets nearly full. maiioc(3) is used to allocate space for the table. 

The corresponding function hdestroy)) frees the memory occupied by the hash table so that a new table can be constructed, 
item isoftype entry, which is a typedef defined in <search.h> and includes these elements: 
typedef struct entry 



} ENTRY; 

key pointsto the zero-terminated ASCII string that isthesearch key. data pointsto the data associated with that key. (A 
pointer to a type other than character should be cast to pointer-to-character.) hsearch ((searches the hash tableforan item 
with the same key as i tem, and if successful returns a pointer to it. act i on determines what hsearch o does after an unsuccess¬ 
ful search. A value of enter instructs it to insert the new item, whereas a value of find means to return null. 
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RETURN VALUE 

hcreateo returns null if the hash table cannot be successfully installed. 

hsearcho returns null if act i on is enter and there is insufficient memory to expand the hash table, or if act i on is find and 

i t em cannot befound in the hash table 

C0NF0RMST0 

SV ID, except that in SysV, the hash table cannot grow. 

BUGS 

The implementation can manage only one hash table at a time. Individual hash table entries can be added, but not deleted. 

EXAMPLE 

The following program inserts 24 items into a hash table and then prints some of them: 

#include <stdio.h> 

#include <search.h> 

char *data[ ]={ "alpha", "bravo", "Charley", "delta", 

"echo", "foxtrot", "golf", "hotel", "india", "juliette", 

"kilo", "lima", "mike", "november", "oscar", "papa", 

"quebec", "romeo", "sierra", "tango", "uniform", 

"victor", "whiskey", "x-ray", "yankee", "zulu" 


/* start with small table, and let it grow */ 
hcreate(3); 

for (i = 0; i < 24; t ++) 


/* data is just an integer, instead of a pointer 
to something */ 
e. data = (char *)i ; 
ep = hsearch(e, ENTER); 

/* there should be no failures */ 

if (ep == NULL) (fprintf(stderr, "entry failed\n"); exit(1);} 

} 

for (i = 22; i < 26; i ++) 

/* print two entries from the table, and show that 
two are not in the table */ 



ep = hsearch(e, FIND); 

printf("%9.9s -> %9.9s:%d\n", e.key, ep?ep->key :"NULL", 
ep?(int)(ep->data ):0); 



SEE ALSO 

bsearch(3), lsearch(3), tsearch(3), malloc(3) 


GNU, 30 September 1995 
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hypot 

hypot- Euclidean distance function 

SYNOPSIS 

#include <math.h> 

double hypot(double *, double y); 

DESCRIPTION 

The hypot o function returnsthesqrt(x*x+y*y). This is the length of the hypotenuse of a right-angle triangle with sides of 
length x and y, or the distance of the point (x, y) from the origin. 

C0NF0RMST0 

SVID 3, BSD 4.3 

SEE ALSO 

sqrt(3) 

25Junel993 


index,rindex 

index, rindex— Locate character in string 

SYNOPSIS 

#include <string.h> 

char *index(const char *s,int c); 

char *rindex(const char *s,int c); 

DESCRIPTION 

The index)) function returns a pointer to thefirst occurrence of the character c in the strings. 

The rindexo function returns a pointer to the last occurrence of the character c in the strings. 

The termi nati ng null character is considered to be a part of the strings. 

RETURN VALUE 

The index o and rindexo functions return a pointer to the matched character, or null if the character is not found. 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

memchr(3), strchr(3), strpbrk(3), strrchr(3), strsep(3), strspn(3), strstr(3), strtok(3) 

GNU, 12 April 1993 

inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, 
inet_lnaof,inet_netof 

inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, inet_lnaof, inet_netof— Internet address-manipulation 
routines 
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SYNOPSIS 

#include <sys/socket.h> 

#include <netinet/in.h> 

#include <arpa/inet.h> 

int inet_aton(const char *cp, struct in_addr *inp); 
unsigned long int inet_addr(const char *cp); 
unsigned long int inet_network(const char *cp); 
char *inet_ntoa(struct in_addr in); 
struct in_addr inet_makeaddr(int net, int host); 
unsigned long int inet_lnaof(struct in_addr in); 
unsigned long int inet_netof(struct in_addr in); 

DESCRIPTION 

inet_aton() converts the I nternet host address c p from the standard numbers-and-dots notation into binary data and stores it 
in the structure that inp points to. inet_aton returns nonzero if the address is valid, and 0 if it is not. 

T he inet_addr( (function converts the I nterndt host address cp from numbers-and-dots notation into binary data in network 
byte order. If theinput isinvalid, -1 is returned. Thisisan obsolete interface to inet_aton; it is obsolete because -1 isa valid 
address(255.255.255.255), and inet_aton provides a cleaner way to indicate error return. 

The inet_network( ) function extracts the network number in network byte order from the address cp in numbers-and-dots 
notation. If theinput isinvalid, -1 isreturned. 

The inet_ntoa( ) function convertsthe Internet host address given in network byte order to a string in standard numbers- 
and-dots notation. The string isreturned in a statically allocated buffer, which subsequent calls will overwrite. 

T he inetjnakeaddr () function makes an Internet host address in network byte order by combining the network number net 
with the local address ho s t in network net , both in local host byte order. 

The inet_inaof () function returnsthe local host address part of the I nternet address i n. The local host address is returned in 
local host byte order. 

The inet_netof( (function returnsthe network number part of the I nternet address i n. The network number is returned in 
local host byte order. 

The Structure in_addr as used in inet_ntoa(), inetjnakeaddr (), inet_lnoaf (), and inetjietof () is defined in netinet/in.h as 
struct in_addr { 
unsigned long int s_addr; 

} 

Note that on the i80x86 the host byte order is Least Significant Byte first, whereas the network byte order, as used on the 
Internet, is M ost Significant Byte first. 

CONFORMSTO 

BSD 4.3 


SEE ALSO 

gethostbyname(3), getnetent(3), hosts(5), networks(5) 


BSD, 3 September 1995 


infnan 

int nan— Deals with infinite or not-a-number (N aN) result 

SYNOPSIS 

#include <math.h> 
double infnan(int error); 
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DESCRIPTION 

Theinfnano function returns a suitable value for infinity and not-a-number (N aN) results. The value of error can beERANGE 
to represent infinity, or anything else to represent N aN. errno isalso set. 

RETURN VALUE 

If error isERANGE (Infinity), huge_val is returned. 

Iferror is -erange (-Infinity), -huge_val is returned. 

If error isanything else, NaN isreturned. 

ERRORS 

erange Thevalueof error ispositiveor negative infinity. 

edom Thevalueof error is not-a-number (N aN). 

C0NF0RMST0 

BSD 4.3 

GNU, 2 Junel993 


initgroups 

initgroups- Initializes the supplementary group access I i st 

SYNOPSIS 

#include <grp.h> 

#include <sys/types.h> 

int initgroups(const char ‘user, gid_t group); 

DESCRIPTION 

The initgroups)) function initializes the group access list by reading the group database/etc/group and using all groups of 
whichuser isa member. The additional group gr oup isalso added to the list. 

RETURN VALUE 

The initgroups)) function returns0 on success, or -i if an error occurs. 

ERRORS 

eperm The calling process does not have sufficient privileges. 

enomem Insufficient memory to allocate group information structure. 

FILES 

/etc/group group database file 

C0NF0RMST0 

SVID 3, BSD 4.3 

SEE ALSO 

getgroups(2), setgroups(2) 


GNU, 5 April 1993 
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inndcomm— IN N D communication part of InterN dtN ews library 

SYNOPSIS 



DESCRIPTION 

The routines described in this manual page are part of the InterN etN ews library, iibinn(3). They are used to send com¬ 
mands to a running innd(8) daemon on the local host. The letters/CC stand for Innd Control Command, 
iccopen creates a U N IX-domain datagram socket and bindsit to the server's control socket. It returns-i on failure or 0 on 
success. This routine must be called before any other routine. 

iccciose doses any descriptors that have been created by iccopen. It returns-1 on failure or 0 on success, 
iccsettimeout can be called before any of thefollowing routines to determine how long the library should wait before giving 
upon getting the server's reply. This isdone by setting and catching a sigalrm stgnai(2). If the timeout is less than 0, no 
reply will be waited for. Thesc_SHUTDOWN, sc_xabort, and sc_xexec commands do not get a reply either. The default, which 
can be obtained by setting the timeout to 0 , is to wait until the server replies 

icccommand sends the command cmd with parametersargv totheserver. It returns-1 on error. If the server replies, andrepi yp 
is not null, it will be filled in with an allocated buffer that containsthefull text of the server's reply. This buffer is a string in 
the form <di gi t s ><s pac e><t ext > where d gits is the text value of the recommended exit code; 0 indicates success Replies 
longer than 4,000 bytes will be truncated. The possible values of cmd are defined in the inndcomm. h header file. The param¬ 
eters for each command are described in ctnnnd(8). This routine returns-1 on communication failure; on success it returns 
the exit status sent by the server, which will never be negative. 

icccancei sendsacancel message to the server, mesgi d isthe message ID of the article that should be canceled. The return 
valueisthesameasfor icccommand. 

iccpause, iccreserve, and iccgo send a pause, reserve or go command to the server, respectively. If iccreserve is used, the 
why value used in theiccpause invocation must match; the value used in theiccgo invocation must always match the one 
used in theiccpause invocation. The return value for all three routines is the same as for icccommand. 

If any of these routines fail, the icctaiiure variable will identify the system call that failed. 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 



SEE ALSO 

ctlinnd(8), innd(8), libinn(3). 
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insque,remque 

insque, remque— I nsert/Removean item from a queue 

SYNOPSIS 

#include <stdlib.h> 

void insque(struct qelem * eI em, struct qelem * pr ev); 
void remque(struct qeI em*eI em); 

DESCRIPTION 

insque o and remque o are functions for manipulating queues made from doubly linked lists. Each element in this list is of 
type struct qelem. 

The qelem structure is defined as 
struct qelem { 
struct qelem *q_forw; 
struct qelem *q_back; 
char q_data[1]; 

}; 

insque o inserts the element pointed to by e i e m immediately after the element pointed to by prev, which must not be null. 
remque () removes the element poi nted to by e i e m from the doubly linked list. 

C0NF0RMST0 

SVR4 

BUGS 

The q_data field issometimes defined to be of type char *,and under Solaris 2.x, it doesn't appear to exist at all. 

The location of the prototypes for these functions differs among several versions of U NIX. Some systems place them i n 
<search.h>, othersin <string.h>. Linux places them in <stdiib.h> because that seems to make the most sense 
Some versions of UNIX (suchasHP-UX 10.x) do not define a struct qelem but rather have the arguments to insque o and 
remque () be Of type void *. 

GNU,30 October 1996 



isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, 
islower, isprint, ispunct, isspace, isupper,isxdigit 

isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit— 
Character classification routines 


SYNOPSIS 


#include <ctype.h> 
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DESCRIPTION 

These functions check whether c , which must have the value of an unsigned char or eof, falls into a certain character class 
according to the current locale: 

isainumo Checksforan alphanumeric character; it isequivalent to (isaipha(c) || isdigit(c)). 

isaiphao Checksforan alphabetic character; in the standard C locale, it is equivalent to (isupper(c) 11 

isiower(c)) . In some locales, there may be additional characters for which isaiphao i s true— 
letters that are neither uppercase nor lowercase. 

isascno C hecks whether c isa 7-bit unsigned char value that fits into the ASCII character set. This 

function isa BSD extension and isalso an SVID extension, 
isbianko C hecksfor a blank character; that is, a space or a tab. Thisfunction isaGN U extension, 

iscntno C hecksfor a control character, 

isdigito C hecksfor a digit (0 through 9). 

isgrapho C hecksfor any printable character except space 

isiower( ) C hecksfor a lowercase character, 

isprinto C hecksfor any printable character, including space 

ispuncto C hecksfor any printable character that is not a space or an alphanumeric character, 

isspaceo C hecksfor whitespace characters They are space form-feed ('\f'), newline ( 1 \n ■), carriage 

return ( 1 \r'), horizontal tab ( 1 \t•), and vertical tab (■ \v 1 ). 
isuppero Checksforan uppercase letter. 

isxdigito C hecksfor a hexadecimal digit (that is, oneof01234567890abcdefABCD EF). 

RETURN VALUE 

T he values returned are nonzero if the character c falls into the tested class, and e if it does not. 


C0NF0RMST0 

ANSI C, BSD 4.3. isascno isa BSD extension and isalso an SVID extension, isbianko isaGN U extension. 

BUGS 

The details of what characters belong in which class depend on the current locale For example, isuppero will not recognize 
an A with an umlaut (A) as an uppercase letter in the default C locale 

SEE ALSO 

tolower(3), toupper(3), setlocale(3), ascii(7), locale(7) 

GNU, 2 September 1995 


isatty 

isatty— T ests whether this descri ptor refers to a terminal 

SYNOPSIS 

#include <unistd.h> 
int isatty (int des c ); 

DESCRIPTION 

isatty returns i if desc is an open descriptor connected to a terminal, and 0 otherwise. 
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CONFORMSTO 

SVID,AT&T,X/OPEN,BSD 4.3 

SEE ALSO 

fstat(2), ttyname(3) 

Linux, 20 April 1995 


isinf,isnan,finite 

isinf, isnan, finite— Test for infinity or not-a-number (N aN) 


SYNOPSIS 

#include <math.h> 
int isinf(double value); 
int isnan(double value); 
int finite(double value); 

DESCRIPTION 

T he isinf o function returns -i if value represents negative infinity, i if value represents positive infinity, and 0 otherwise. 

T he isnan 0 function returns a nonzero value if va 1 ue is not-a-number (N aN), and 0 otherwise. 

Thefimteo function returns a nonzero value if vai ue isfiniteor is not a not-a-number (NaN) value, and 0 otherwise. 

CONFORMSTO 

BSD 4.3 

GNU, 2 Junel993 


j0.jl.jn, y0,yl,yn 

j 0 , ji, jn, y 0 , yi, yn— Bessel functions 

SYNOPSIS 

#include <math.h> 
double j0(double x); 
double jl(double x); 
double jn(int n, double x); 
double y0(double x); 
double yl(double x); 
double yn(int n, double x); 

DESCRIPTION 

The j 0 () and ji() functions return Bessel functionsof x of thefirst kind of orders 0 and 1, respectively. The jn( (function 
returns the Bessel function of x of thefirst kind of order n. 

The y@( ) and yio functions return Bessel functionsof x of the second kind, ordersO and 1, respectively. T he yn( (function 
returns the Bessel function of x of the second kind, order n . 

For thefunctions y@(), yi(> and yn o,the value of x must be positive For negative values ofx, these functions return 

-HUGE_VAL. 

CONFORMSTO 

SVID 3, BSD 4.3 





Part III: L ibrary Functions 


960 


BUGS 

There are errors of up to 2e-16 in the values returned by joo, ji (), and jn() for values of * between -8 and 8. 

26Junel993 


killpg 

knipg— Sendsasignal to all members of a process group 

SYNOPSIS 

#include <signal.h> 

int killpg(pid_t pidgr p, int signal ); 

DESCRIPTION 

Thekiiipgo function causesthesignal si gnai to be sent to all the processes in the process group pi dgr p or to the processes' 
own process group if pidgrp is equal to 0. 

It is equivalent to klll( -pidgrp, signal);. 

RETURN VALUE 

T he value returned is -i on error, or 0 for success 

ERRORS 

Errors are returned in errno and can be one of the following: 

einval Signal is invalid. 

esrch Processgroup does not exist. 

eperm The user ID of the calling process is not equal to that of the process the signal is sent to, and the user ID is 

not that of the super-user. 

SEE ALSO 

kill(2), signal(2), signal(7) 

GNU, 4 April 1993 


labs 

labs- C omputes the absolute value of a long integer 

SYNOPSIS 

#include <stdlib.h> 
long int labs (long int j ); 

DESCRIPTION 

T he labs 0 function computes the absolute value of the long integer argument j. 

RETURN VALUE 

Returns the absolute value of the long integer argument. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 
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NOTES 

T rying to take the absolute value of the most negative integer is not defined. 

SEE ALSO 

abs(3), cell(3), floor(3), fabs(3), rlnt(3) 

GNU, 6Junel993 


ldexp 

idexp— M ulti plies floating-point number by integral power of 2 

SYNOPSIS 

#include <math.h> 

double ldexp(double x, int exp); 

DESCRIPTION 

The idexp () function rdturnsthe result of multiplying the floating-point number x by 2 raised to the power exp. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

frexp(3), modf(3) 

BSD, 6Junel993 


ldiv 

idiv- Computes the quotient and remainder of long integer division 

SYNOPSIS 

#include <stdlib.h> 

ldiv_t ldiv(long int numer, long int denom); 

DESCRIPTION 

Theidivo function computes the value numer/denom and returns the quotient and remainder in a structure named idiv_t 
that containstwo long integer members named quot and rem. 

RETURN VALUE 

T he idiv_t structure 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

div(3) 

GNU, 29 March 1993 
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lgamma 

lgamma— Logs gamma function 

SYNOPSIS 

#include <math.h> 
double lgamma(double x); 

DESCRIPTION 

The lgamma o function returns the log of the absolute value of theGamma function. The sign of the Gamma function is 
returned in the external integer si gngam. 

For negative integer values of x, lgammao returns huge_val, and errno issdtto erange. 

ERRORS 

erange Invalid argument—negative integer valueof x. 

C0NF0RMST0 

SVID 3, BSD 4.3 

SEE ALSO 

infnan(3) 

BSD, 25Junel993 


libinn 

ubinn— InterN etN ews library routines 

SYNOPSIS 

#include "libinn.h" 
typedef struct _TIMEINF0 { 
timej t i me; 

long t zone; 

} TIMEINFO; 

char *GenerateMessageID() 
void HeaderCleanFrom(f rom)< 

char *HeaderFind(Art i cIe, Header, size) 


FILE *CAopen(FromSer*er, ToServer) 

FILE ‘FromServer ; 

FILE *ToServer ; 

FILE *CAlistopen(FromServer, ToServer, request) 
FILE *FromServer ; 

FILE *ToServer ; 




CAclose() 


libinn 
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struct _DDHANDLE *DDstart(FromServer, ToSer*er) 
FILE *Fr omSer ver ; 

FILE *ToServer ; 

} DDHANDLE; 

void DDcheck(h, group) 

DDHANDLE *¥; 
char ‘group; 

char * DDend(h) 

DDHANDLE *h; 

void CloseOnExec(f d, flag) 



int SetNonBlocking(fd, flag) 



int LockFile(fd, flag) 



char * GetConfigValue(val ue) 

char * GetFileConfigValue(val ue) 
char *val ue; 

char * GetFQDN() 

char * GetModeratorAddress(group) 
char ‘group; 

int GetResourcellsage(usert i me, systime) 
double *us e r t i me; 
double *s y s t i me; 

int GetTimelnfo(now) 

TIMEINFO: *$*•; 

int NNTPlocalopen(FromServerp, ToServerp, errbuff) 

FILE “FromServerp ; 

FILE “ToServerp; 
char ‘errbuff ; 

int NNTPremoteopen(FromServerp, ToServerp, errbuff) 
FILE “FromServerp ; 

FILE “ToServerp; 
char ‘errbuff ; 

int NNTPconnect(host, FromServerp, ToServerp, errbuff) 

FILE “FromServerp; 

FILE “ToServerp; 
char ‘err buff ; 


NNTPcheckarticle(text) 
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int NNTPsendarticle(t ext, ToServer, Tee) 
FILE *ToServer ; 


int NNTPsendpassword(ser v e r, FromServer, ToServer) 
char ‘server ; 

FILE ‘FromServer ; 

FILE ‘ToServer ; 

void Radix32(val ue. p ) 
unsigned long value; 

char * ReadInFile(name, Sbp) 
struct stat ‘Slip; 
char * ReadInDescriptor(fd, Sbp) 
struct stat ‘Sbp; 


char * INNVersion() 

DESCRIPTION 

libinn is a Ii brary of utility routines for manipulating U senet articles and related data. It is not necessary to use the header file 
libinn.h; if it isnot available, it isonly necessary to properly declare the timeinfo datatype as shown in the preceding code 
GenerateMessageiD uses the current time process ID, and fully qualified domain name of the local host to create a M essage 
ID header that is highly likely to be unique The returned value points to static space that isreused on subsequent calls 
HeadercieanFrom removes the extraneous information from the value of a From or Repiy-To header and leaves just the official 
mailing address. In particular, the following transformations are madeto thefrom parameter: 
address -> address 


stuff <address>-> address 

The transformations are simple and are based on RFC 1036, which limits the format of the header. 

HeaderFind searches through Arti ci e looking for the specified Header .size should be the length of the header name It 
returns a pointer to the value of the header, skipping leading whitespace, or null if theheader cannot be found. Arti ci e 
should be a standard C string containing thetext of the article; the end of a header isindicated by a blank line: two 
consecutive \n characters. 

CAopenand cAciose provide news clients with access to the active file; thecA stands for Client Active. CAopen opens the 
active(5) file for reading. It returns a pointer to an open file, or null on error. If a local or an N FS-mounted copy exists, 
CAopen will use that file. The FromServer and ToServer parameters should be files connected to theN NTP server for input 
and output, respectively. (See the discussions of NNTPremoteopen and NNTPiocaiopen later in thissection.) If either parameter is 
null, CAopen will just return null if the file is not locally available. If neither is null, CAopen will use them to query theN NTP 
server using the "list" command to make a local temporary copy. 

ThecAiistopen sends a "list" command to the server and returns a temporary file containing the results Ther eques t 
parameter, if not null, will be sent as an argument to the command. Unlike CAopen, this routine will never use a locally 
available copy of the active file. 

CAciose closes the active file and removes any temporary file that might have been created by CAopen or CAiistopen. 
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cioseOnExec can make a descri ptor close-on-exec so that it isnot shared with any child processes. If theflag isnonzero, thefile 
is so marked; if it isa, the dose-on-exec mode is cleared. 

DDstart, DDcheck, and DDend are used to set the Distribution header; the dd stands for D efault D istribution. The 
distrib.pats(5) file isconsulted to determinethe proper valuefor the Distribution header after all newsgroups have been 
checked. DDstart beginsthe parsing. It returnsa pointer to an opaque handle that should be used on subsequent calls. T he 
f r o ms e r v e r and ToSer *er parameters should be files connected to the N NTP server for input and output, respectively. If 
either parameter isNULL, an empty default will ultimately be returned if thefile is not locally available. 

DDcheck should be called with the handle, h, returned by DDstart and a new group, group, to check. It can be called as often as 
necessary. 

DDend releases any state maintained in the handle and returns an allocated copy of the text that should be used for the 
Distribution header. 

setNonBiocking enables (if f i ag isnonzero) or disables (if f i ag iso) non-blocking I/O on the indicated descriptor. It returns 
-i on failure and 0 on success 

LockFiie tries to lock thefile descriptor fd. If f 1 ag isnonzero it will block until the lock can be made; otherwise it will return 
-1 if thefile cannot be locked. It returns-1 on failure and 0 on success 

Getcontigvaiue returns the value of the specified configuration parameter. (See inn. cont (5) for details on the parameters and 
their interpretation.) The returned value points to static space that isreused on subsequent calls 
GetFiieConfigvaiue returns the specified configuration parameter from the inn. cont file without checking for any defaults. 
The returned value points to static space that is reused on subsequent calls or null if the value is not present. 

GetFQDN returns the fully qualified domain name of the local host. The returned value points to static space that isreused on 
subsequent calls, or null on error. 

GetModeratorAddress returns the mailing address of the moderator for the specified group or null on error. (See moderators(5) 
for details on how the address is determined.) GetModeratorAddress does no checking to see if the specified group is actually 
moderated. The returned value points to static space that isreused on subsequent calls. 

GetResourceusage fills in theusert i me and syst i me parameters with the total user and system time used by the current process 
and any children it may havespawned. It gets the values by doing a ttmes(2) system call. It returns-1 on failure, oroon 
success. 

GetTimeinfo fills in thenow parameter with information about the current time and t zone. Theti me andusec fields will be 
filled in by a call to gettimeofday(2). Theti me field will be filled in by a call to time(2), and the usee field will be set to 0.The 
t zone field will be filled in with the current offset from GMT. This is done by calling iocaitime(3) and taking the value of 
the t m_ g mi of f field, negating it, and dividing it by 60. T his is done by calling iocaitime(3) and comparing the value with that 
returned by a call to gmtime(3). For efficiency, thet zone field is only recalculated if more than an hour has passed since the 
last time GetTimeinfo was called. T his routine returns-i on failure, and 0 on success. 

NNTPiocaiopen opens a connection to the private port of an I nterNetNews server running on the local host. It returns-1 on 
failure, or 0 on success Fromsemrp and Toser ver p will be filled in with files that can be used to communicate with the 
server, e r r b uf f can either be null or a pointer to a buffer at least 512 bytes long. I f it is not null, and the server refuses the 
connection, it will be filled in with the text of the server's reply. This routine is not for general use; it isa subroutine for 
compatibility with systems that have U NIX-domain stream sockets It always returns-1. 

NNTPremoteopen does the same as NNTPiocaiopen, except that it calls Getcont igvaiue to find the name of the local server and 
opens a connection to thestandard N NTP port. Any client program can use this routine. It returns-i on failure, or@ on 
success. 

NNTPconnect is the same as NNTPremoteopen, except that the desired host is given as the host parameter. 

NNTPcheckarticie verifies that the text meets theNNTP limitations on line length. It returns-1 on failure, or 0 if the text is 
valid. 
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NNTPsendarticie writes text on ToServer using N NTP conventions for line termination. Thetext should consist of oneor 
more lines ending with a newline. If Ter mi rate is nonzero, the routine will also write theN NTP data-termination marker on 
thestream. It returns -i on failure, or 0 on success 

NNTPsendpassword sends authentication information to an N NTP server by finding the appropriate entry in the 
passwd.nntp(5) file server contains the name of the host; Getconfigvaiue will be used if server is null. FromServer and 
ToServer should be files that are connected to the server. No action is taken if the specified host is not listed in the password 
file. 

Radix32 converts the number in vai ue into a radix-32 string in the buffer pointed to by p. The number is split into five-bit 
pieces and each piece is converted into a character using the alphabet 0... 9a... v to represent the numbers 0-32. Only the 
lowest 32 bits of value are used, so p need only point to a buffer of eight bytes (seven characters and the trailing \@). 
ReadinFiie readsthefile named name into allocated memory, appending a terminating \o byte. It returnsa pointer to the 
space, or null on error. If sbp is not null, it is taken as the address of a place to store the results of a stat(2) call. 
ReadinDescriptor performs the same function as ReadinFiie, except that td refers to an already-open file. 
iNNVersion returns a pointer to a string identifying thel N N version, suitable for printing in logon banners 

EXAMPLES 

char *Arti cl e ; 
char I##| 2 56 ] ; 

FILE *F; 

FILE *T 0 5 e r v e r ; 

FILE ‘FromServer ; 

if ((p = HeaderFind(Article, "From", 4)) == NULL) 

Fatal)"Can't find From line"); 

(void)strcpy(buff, p); 

HeaderCleanFrom(l)uf f ); 

if ((F = CAopen(FromServer, ToServer)) == NULL) 

Fatal)"Can't open active file"); 

/* Don't pass the file on to our children. */ 

CloseOnExec(fileno(F), 1); 

/* Make a local copy. */ 

p = ReadInDescriptor(fileno(F), (struct stat *)NULL); 

/* Close the file. */ 

CAclose)); 

if (NNTPremoteopen(&FromServer , &ToServer ) < 0) 

Fatal)"Can't connect to server"); 
if )(p = GetModeratorAddress("comp.sources.unix")) == NULL) 

Fatal("Can't find moderator's address"); 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

active(5), dbz(3z), parsedate(3), inn.conf(5), inndcomm(3), moderators(5), passwd.nntp(5) 

GNU, 30 October 1996 
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SYNOPSIS 

#include <pbm.h> 
cc ... libpbm.a 

D ESC RIPTIO N - PAC KAG EW ID E RO U TIN ES 

The following sections describe string and file management routines available in libpbm. 

KEYWORD MATCHING 

T he following does a case-in sensitive match of s t r against keyword: 

int pm_keymatch( char* str, char* keyword, int mi nchars ) 

str can be a leading substring of keyword, but at least mi nchars must be present. 

LOG BASE TWO 

This converts between amaxvai and the minimum number of bits required to hold it: 
int pm_maxvaltobits(int ma x v a I ) 
int pm_bitstomaxval(int bits) 

MESSAGES AND ERRORS 

This is a printf () -style routine to write an informational message 

void pm_message(char* f mt, ... ) 

This is a printf () style routine to write an error message and abort: 

void pm_error(char* f mt , ... ) 

Thefollowingwritesausage message; thestring should indicate what arguments are to be provided to the program: 

void pm_usage(char* usage) 

GENERIC FILE MANAGEMENT 

Thefollowing opens the given filefor reading, with appropriate error checking: 

FILE* pm_openr(char* name) 

A filenameof - istaken as equivalent to stdin. 

Thefollowing opens the given filefor writing, with appropriate error checking: 

FILE* pm_openw(char* name) 

Thefollowing closesthefile descriptor, with appropriate error checking: 

void pm_close(FILE* fp) 

ENDIAN I/O 

Thefollowing are routines to read and write short and longintsin either big- or little-endian byte order: 

int pm_readbigshort(FILE* in, short* sP) 
int pm_writebigshort(FILE* out , short s) 
int pm_readbiglong(FILE* in, long* IP) 
int pm_writebiglong(FILE* out , long I) 
int pm_readlittleshort(FILE* in, short* sP) 
int pm_writelittleshort(FILE* out , short s) 
int pm_readlittlelong(FILE* in, long* IP) 
int pm_writelittlelong(FILE* out , long I ) 

DESCRIPTION-PBM-SPECIFIC ROUTINES 

Thefollowing sections describe file management routines available in libpbm. 



Part III: Library Functions 

TYPES AND CONSTANTS 

Each bit should contain only the values of pbm_white or pbm_black: 
typedef ... bit; 

#define PBM_WHITE ... 

#define PBM_BLACK ... 

These are routines for distinguishing different file formats and types: 

#define PBM_FORMAT ... 

#define RPBM_FORMAT ... 

#define PBM_TYPE PBM_FORMAT 
#define PBM_FORMAT TYPE(f) ... 

INITIALIZATION 

All PBM programs must call this routine: 

void pbm_init(int* argcP, char* argv[] ) 

MEMORY MANAGEMENT 

This allocates an array of bits 

bit** pbm_allocarray(int cols, int rows) 

This allocates a row of the given number of bits: 

bit* pbm_allocrow(int cols) 

This frees the array allocated with pbm_aiiocarray() containing the given number of rows 
void pbm_freearray(bit** bits, int rows) 

This frees a row of bits: 
void pbm_freerow(bit* bitrow) 

READING FILES 

This reads the header from a PBM file filling in the rows, col s, and format variables: 

void pbm_readpbminit(FILE* fp, int* coIsP, int* rowsP, int* formatP) 

This reads a row of bits i nto the b i t r o w array (f or mat and c o i s are filled i n by pbm_readpbminit ()): 

void pbm_readpbmrow(FILE* fp, bit* bit row, int cols, int format) 

This function combines pbm_readpbminit(), pbm_allocarray( ), and pbm_readpbmrow( ): 
bit** pbm_readpbm(FILE* fp, int* coIsP, int* rowsP) 

It reads an entire bitmap file into memory, returning the allocated array and filling in the rows and cols variables. 

This reads an entire file or input stream of unknown size to a buffer and allocates more memory as needed: 

char* pm_read unknown size(FILE* fp, long* nread) 

T he calling routine has to free the allocated buffer with t reeo. pm_read_unknown_size ( ) returns a pointer to the allocated 
buffer; the nr ead argument returns the number of bytes read. 

WRITING FILES 

T his writes the header for a portable bitmap fi le: 

void pbm_writepbminit(FILE* fp, int cols, int rows, int forccplai n) 

T he f o r c e p i a i n fl ag forces a plai n-format fi le to be written, as opposed to a raw-format one 
T his writes a row from a portable bitmap: 

void pbm_writepbmrow(FILE* fp, bit* bitrow, int cols, int forceplain) 
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This writes the header and all data for a portable bitmap: 

void pbm_writepbm(FILE* fp, bit** bits, int cols, int rows, int forceplai n) 

This function Combines pbm_writepbminit() and pbm_writepbmrow(). 

SEE ALSO 

libpgm(3), libppm(3), libpnm(3) 

AUTHOR 

Copyright® 1989,1991 by Tony Hansen andjef Poskanzer 

libpgm 

libpgm— Functionsto support portablegraymap programs 

SYNOPSIS 

#include <pgm.h> 

cc ... libpgm.a libpbm.a 

DESCRIPTION 

T he following sections describe memory and file management routines available in libpgm. 

TYPES AND CONSTANTS 

Each gray should contain only the values between 0 and pgmjiaxmaxval. 

pgm_pbmmaxvai is the max va i usedwhenaPGM program reads a P B M file Normally it is i, but for some programs a larger 
value gives better results 

typedef ... gray; 

#define PGM_MAXMAXVAL ... 
extern gray pgm_pbmmaxval; 

T hefollowing are for distinguishing different file formats and types 

#define PGM_FORMAT ... 

#define RPGM_FORMAT ... 

#define PGM_TYPE PGM FORMAT 
int PGM_FORMAT_TYPE{int format) 

INITIALIZATION 

All PGM programs must call this routine: 

void pgm_init(int* argcP, char* argv[] ) 

MEMORY MANAGEMENT 

This allocates an array of grays 

gray** pgm_allocarray(int cols, int rows) 

This allocates a row of the given number of grays 

gray* pgm_allocrow(int cols) 

This frees the array allocated with pgm_aiiocarray() containing the given number of rows 
void pgm_freearray(gray** grays, int rows) 

Thisfreesarow of grays 
void pgm_freerow(gray* grayrow) 
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READING FILES 

This reads the header from a PGM file, filling in therows, col s, ma x v a i , and for mat variables: 

void pgm_readpgminit(FILE* fp, int* cols P, int* r o ws P, gray* ma x v a IP, 

This reads a row of grays into the grayrow array, format, coi s, and maxvai are filled in by pgm_readpgminito: 
void pgm_readpgmrow(FILE* fp, gray* grayrow, int cols, gray maxvai , int format) 

This function combines pgm_readpgminit(), pgm_allocarray(), and pgm_readpgmrow() : 
gray** pgm_readpgm(FILE* fp, int* coIsP, int* r o ws P, gray* maxvalP) 

It reads an entire graymap file into memory, returning the allocated array and filling in therows, cols, and ma x v a i variables 

WRITING FILES 

This writes the header for a portable graymap file 

void pgm_writepgminit( FILE* fp, int cols, int rows, gray maxvai , 
int forceplain ) 

Thef orcepi ai n flag forces a plain-format file to be written, as opposed to a raw-format one 
This writes a row from a portable graymap: 

void pgm_writepgmrow(FILE* fp, gray* grayrow, int cols, gray maxvai , 
int forceplain) 

Thisfunction combines pgm_writepgminito and pgmjvritepgmrowo; it writes the header and all data for a portable graymap: 
void pgm_writepgm( FILE* fp, gray** grays, int cols, int rows, gray maxvai , int forcepl ai n ) 

SEE ALSO 

libpbm(3), libppm(3), libpnm(3) 

AUTHOR 

Copyright ® 1989,1991 by Tony H ansen and J ef Poskanzer. 

libpnm 

libpnm— Functionsto support portableanymap programs 

SYNOPSIS 

ffinclude <pnm.h> 

cc ... libpnm.a libppm.a libpgm.a libpbm.a 

DESCRIPTION 

T he following sections describe memory and file management routines available in libpnm. 

TYPES AND CONSTANTS 

Each xei contains three xeivais, each of which should contain only a value between 0 and pnm_maxmaxval. pnm_pbmmaxvai is 
themaxvaiusedwhenaPNM program reads a PBM file. Normally it is 1 , but for some programs, a larger value gives better 
results. 

typedef ... xel; 
typedef ... xelval; 

#define PNM_MAXMAXVAL ... 
extern xelval pnm_pbmmaxval; 



XEL MANIPULATIONS 

This macro extracts a single value from an xei when you know it'sfrom a PBM or PGM file: 

xelval PNM_GET1( xel x ) 

When the xei is from a PPM file use ppm_getr(), ppm_getgo, and ppm getbo. 

This macro assigns a single value to an xei when you know it'sfrom a PBM or PGM file: 

void PNM_ASSIGN1( xel x, xelval v ) 

W hen the xei is from a P P M file use ppm_assign (). 

This macro checks two xeisfor equality: 

int PNM_EQUAL( xel x, xel y ) 

This one isfor distinguishing different file types: 

int PNM_FORMAT TYPE( int format ) 

INITIALIZATION 

All PNM programs must call this routine: 

void pnm_init( int* argcP, char* argv[] ) 

MEMORY MANAGEMENT 

This allocates an array of xeis 

xel** pnm_allocarray( int cols, int rows ) 

This allocates a row of the given number of xeis 

xel* pnm_allocrow( int cols ) 

This frees the array allocated with pnm_aiiocarray() that contains the given number of rows 
void pnm_freearray( xel** xeis, int rows ) 

Thisfreesarow of xeis: 

void pnm_freerow( xel* xelrow ) 

READING FILES 

This reads the header from a PN M file, filling in the rows, cols, maxvai, and format variables 
void pnm_readpnminit( FILE* fp, int* colsP, int* rowsP, xelval* maxvalP, 
int* formatP ) 

This reads a row of xeis into the xelrow array, format, cols, and maxvai are filled in by pnm_readpnminit(): 

void pnm_readpnmrow( FILE* fp, xel* xelrow, int cols, xelval maxvai, int format ) 

This reads an entire anymap file into memory, returning the allocated array and filling in the rows, cols, maxvai, and format 
variables: 

xel** pnm_readpnm( FILE* fp, int* colsP, int* rowsP, xelval* maxvalP, 
int* formatP ) 

Thisfunction combines pnm_readpnminit(), pnm_aiiocarray(),and pnm_readpnmrow(). U nlike the equivalent functions in 
PBM, PGM, and PPM, it returns the format so you can tell what type the file is. 

WRITING FILES 

This writes the header for a portable anymap file: 

void pnm_writepnminit( FILE* fp, int cols, int rows, xelval maxvai, int format, 
int force-plain) 
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Unlike the equivalent functions in PBM, PGM, and PPM, you have to specify the output type The forcepiain flagforcesa 
plain-format file to be written, as opposed to a raw-format one. 

This writes a row from a portable anymap: 

void pnm_writepnmrow( FILE* fp, xel* xelrow, int cols, xelval maxval, int format, 

This writes the header and all data for a portable anymap: 

void pnm_writepnm( FILE* fp, xel** xels, int cols, int rows, xelval maxval, int format, 

This function combines pnm_writepnminit() and pnm_writepnmrow(). 

FORMAT PROMOTION 

This promotesa row of xelsfrom one maxval and format to a new set: 

void pnm_promoteformatrow( xel* xelrow, int cols, xelval maxval, int format, xelval new-maxval, 
int newformat ) 

U se this when combining multiple anymaps of different types- just take the maximum value of themaxvais and the max of 
the formats, and promote them all to that. 

This promotes an entire anymap: 

void pnm_promoteformat( xel** xels, int cols, int rows, xelval maxval, 
int format, xelval newmaxval, int newformat ) 

XEL MANIPULATION 

These return a white or black xei, respectively, for the given maxval and format: 
xel pnm_whitexel( xelval maxval, int format ) 
xel pnm_blackxel( xelval maxval, int format ) 

This inverts an xei: 

void pnm_invertxel( xel* x, xelval maxval, int format ) 

Thisfiguresout an appropriate background xei based on this row: 

xel pnm_backgroundxelrow( xel* xelrow, int cols, xelval maxval, int format ) 

Thisfiguresout a background xei based on an entire anymap: 

xel pnm_backgroundxel( xel** xels, int cols, int rows, xelval maxval, 

int format ) 

This can do a slightly better job than pnm_backgroundxeirow(). 

SEE ALSO 

pbm(3), pgm(3), ppm(3) 

AUTHOR 

Copyright e 1989,1991 by Tony H ansen and J ef Poskanzer. 
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libppm 

libppm— Functionsto support portable pixmap programs 

SYNOPSIS 

#include <ppm.h> 

cc ... libppm.a libpgm.a libpbm.a 

TYPES AND CONSTANTS 

typedef ... pixel; 
typedef ... pixval; 

#define PPM_MAXMAXVAL ... 
extern pixval ppm_pbmmaxval; 

Each pixel contai ns three pixvais, each of which should contain only the values between 0 and ppm_maxmaxval. ppm_pbmmaxvai 
isthemaxvai used when a ppm program readsaPBM file Normally it is 1; however, for some programs, a larger value gives 
better results 

For distinguishing different file formats and types, use 

#define PPM_FORMAT ... 

#define RPPM_FORMAT ... 

#define PPM_TYPE PPM_FORMAT 
int PPM_FORMAT_TYPE ( int format ) 

These three macros retrieve the red, green, or blue valuefrom thegiven pixel: 

pixval PPM_GETR( pixel p ) 

pixval PPM_GETG( pixel p ) 

pixval PPM_GETB( pixel p ) 

Thismacro assigns the given red, green, and blue values to the pixel: 

void PPM_ASSIGN( pixel p, pixval red, pixval grn, pixval blu ) 

This macro checks two pixels for equality: 

int PPM_EQUAL( pixel p, pixel q ) 

The following macro scales the colors of pixel p according the old and new maximum values and assigns the new values to 

newp. It is intended to make writing ppm to whatever easier. 

void PPM_DEPTH( pixel newp, pixel p, pixval oldmaxval, pixval newmaxval ) 

Thismacro determines the luminance of the pixel p: 

float PPM_LUMIN( pixel p ) 

MEMORY MANAGEMENT 

Allocate an array of pixels 

pixel** ppm_allocarray( int cols, int rows ) 

Allocate a row of thegiven number of pixels 

pixel* ppm_allocrow( int cols ) 

Freethearray allocated with ppm_aiiocarray() containing the given number of rows 
void ppm_freearray( pixel** pixels, int rows ) 

Free a row of pixels: 

void pbm_freerowf pixel* pixelrow ) 
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READING PBM FILES 

void ppm_readppminit( FILE* fp, int* colsP, int* rowsP, pixval* maxvalP, int* formatP ) 

Read the header from a ppm file, filling in the rows, cois, maxvai, and format variables 

void ppm_readppmrow( FILE* fp, pixel* pixelrow, int cols, pixval maxvai, int format ) 

Read a row of pixels into the ptxeirow array. Format, cois, and maxvai were filled in by ppm readppminito. 
pixel** ppm_readppm( FILE* fp, int* colsP, int* rowsP, pixval* maxvalP ) 

Read an entire pixmap file into memory, returning the allocated array and filling in the rows, cois, and maxvai variables This 
function combi nesppm_readppminit(), ppm_allocarray(), and ppm_readppmrow(). 

WRITING FILES 

void ppm_writeppminit( FILE* fp, int cols, int rows, pixval maxvai, int forceplain ) 

W rite the header for a portable pixmap file. T he forceplain flag forces a plain-format file to be written, as opposed to a raw- 
format one 

void ppm_writeppmrow( FILE* fp, pixel* pixelrow, int cols, pixval maxvai, int forceplain) 

W rite a row from a portable pixmap. 

void ppm_writeppm( FILE* fp, pixel** pixels, int cols, int rows, pixval maxvai, int force-plain) 

W rite the header and all data for a portable pixmap. This function combi nesppm_writeppminito and ppm_writeppmrow<). 

COLOR NAMES 

This line parses an ASC11 color name into a pixel: 

pixel ppm_parsecolor( char* colorname, pixval maxvai ) 

The color can be specified in three ways as a name assuming that a pointer to an X 11-style color names file was compiled 
in; as an X 11-style hexadecimal number (#rgb, #rrggbb, #rrrgggbbb, or#rrrrggggbbbb); or as a triplet of decimal floating 
point numbers separated by commas (r.r,g.g,b.b). 

This line returns a pointer to a string describing the given color: 
char* ppm_colorname( pixel* colorP, pixval maxvai, int hexok ) 

If the X11 color name file is available and the color appears in it, that name is returned. Otherwise, if thehexok flag is true 
then a hexadecimal coiorspec is returned; if hexok isfalseand the X11 color names file is avail able, then the closest matching 
color is returned; otherwise it’s an error. 

SEE ALSO 

pbm(3), pgm(3) 

AUTHOR 

Copyright © 1989,1991 by Tony H ansen and Jef Poskanzer 

localeconv 

locaieconv— Gets numeric formatting information 

SYNOPSIS 

#include <locale.h> 

struct lconv ‘localeconf(void); 
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DESCRIPTION 

Theiocaieconf() function returns a string to a struct iconv for the current locale. 

C0NF0RMST0 

ThiscommandconformstoANSI C and POSIX.1. 

Linux supports the portable locales C and POSIX and also the European Latin-1 ISO-8859-1, and Russian KO1-8 locales. 
The printf () family of functions may or may not honor the current locale 

SEE ALSO 

locale(l), localedef(l), strcoll(3), isalpha(3), setlocale(3), strftime(3), locale(7) 

GNU, 25 April 1993 


longjmp 

longjmp— N onlocal jump to a saved stack context 

SYNOPSIS 

#include <setjmp.h> 

void longjmp(jmp_buf en»,int v a I ); 

DESCRIPTION 

longjmpo and setjmp(3) are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program, 
longjmp o restores the environment saved by the last call of setjmpo with the corresponding env argument. After longjmp o is 
completed, program execution continues as if the corresponding call of setjmpo had just returned the value vai. longjmpo 
cannot cause 0 to be returned. If longjmp is invoked with a second argument of 0,1 will be returned instead. 

RETURN VALUE 

This function never returns 

C0NF0RMST0 

POSIX 

NOTES 

PO SIX does not specify if the signal context will be restored or not. If you want to save restore signal masks, use 
sigiongjmp(3). longjmpo makes programs hard to understand and maintain. If possible, an alternative should be used. 

SEE ALSO 

setjmp(3), sigsetjmp(2), siglongjmp(2) 

25 N ovember 1994 


Ifind,lsearch 

ifind, lsearch— Linear search of an array 

SYNOPSIS 

#include <stdlib.h> 

void *lfind(const void *key, const void *base, size t *nmemb, 
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size_t size,int(*compar )(const void *, const void *)); 

void *lsearch(const void *key, const void *base, size_t ‘nmemb, 

size_t size,int(*c o mp a r )(const void *, const void *)); 

DESCRIPTION 

ltindo and lsearcho perform a linear search for key in thearray base, which has‘nmemb elements of size bytes each. The 
comparison function referenced by compar isexpected to have two arguments that pointto thekey object and to an array 
member, in that order, and which returns zero if the key object matches the array member, and non-zero otherwise 
If lsearch () does not find a matching element, then the key object is inserted at the end of the table and ‘nmemb is 
incremented. 

RETURN VALUE 

Mini o returns a pointer to a matching member of thearray, or null if no match isfound. lsearcho returns a pointer to a 
matching member of the array, or to the newly added member if no match isfound. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

bsearch(3), hsearch(3), tsearch(3) 

GNU, 17 September 1995 


calloc, malloc, free, realloc 

caiioc, maiioc, free, reaiioc- Allocate and free dynamic memory 

SYNOPSIS 

#include <stdlib.h> 

void *calloc(size_t nmemb, size_t size); 
void *malloc(size_t size); 

void ‘realloc(void *ptr, size_t size); 

DESCRIPTION 

caiioc o allocates memory for an array of nmemb elements of size bytes each and returns a pointer to the allocated memory. 
The memory is set to zero. 

maiioc () allocates size bytes and returns a pointer to the allocated memory. T he memory is not cleared. 

freed frees the memory space pointed to by ptr, which must have been returned by a previous call to maiioc o, caiioc o or 

reaiioc(). If ptr isNULL, no operation is performed. 

reaiioco changes the size of the memory block pointed to by ptr to size bytes. The contents will be unchanged to the 
minimum of the old and new sizes; newly allocated memory will be uninitialized. If ptr isNULL, thecall is equivalent to 
maiioc (size); if size isequal to zero, thecall is equivalent to free (ptr). Unless ptr isNULL, it must have been returned by an 
earlier call to malloc(), callocd, or realloc(). 

RETURN VALUES 

For caiiocd and maiioco, the value returned is a pointer to the allocated memory, which is suitably aligned for any kind of 
variable or null if the request fails 
freed returns no value. 




mbiowcs 


FI 


reaiioc ((returns a pointer to the newly allocated memory, which issuitably aligned for any kind of variable and may be 
different from ptr, or null if the request fails or if size was equal to 0 . If reaiioc() fails, the original block is left untouched; 
it is not freed or moved. 

C0NF0RMST0 

ANSI C 


SEE ALSO 

brk(2) 


GNU, 4 April 1993 


mblen 

mbien— D Pterminesthe number of bytes in a character 

SYNOPSIS 

#include <stdlib.h> 
int_mblen(const char *s, size_t n); 

DESCRIPTION 

The mbien 0 function scansthefirst n bytes of thestring s and returns the number of bytes in a character. The mbien 0 
function is equivalent to 

mbtowc((wchat t*)0,s,n); 

except that the shift state of thembtowco function is not affected. 

RETURN VALUE 

T he mbien ((returns the number of bytes in a character, or -1 if the character is invalid, or 0 if it is a null string. 

C0NF0RMST0 

SVID 3, ISO 9899 

SEE ALSO 

mbstowcs(3), mbtowc(3), wcstombs(3), wctomb(3) 

GNU, 29 March 1993 


mbstowcs 

mbstowcs— C onverts a multi byte string to a wide character string 

SYNOPSIS 

#include <stdlib.h> 

size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n); 

DESCRIPTION 

The mbstowcs 0 function converts a sequence of multi byte characters from the arrays into a sequence of wide characters and 
stores up to n wide characters in the array pwc s. 
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RETURN VALUE 

mbstowcso returnsthe number of wide characters stored, or -i if s containsan invalid multibyte character. 

C0NF0RMST0 

SVID 3, ISO 9899 

SEE ALSO 

mblen(3), mbtowc(3), wcstombs(3), wctomb(3) 

GNU, 29 March 1993 


mbtowc 

mbtowc — C onverts a multibyte character to a wide character 

SYNOPSIS 

#include <stdlib.h> 

int mbtowc(wchan_t *pwc, const char *s, size_t n); 

DESCRIPTION 

The mbtowc o function converts a multi byte characters, which is no longer than n bytes, into a wide character and, ifpwc is 
not null, stores the wide character in pwc. 

RETURN VALUE 

mbtowc () returnsthe number of bytes in the multi byte character, or -i if the multi byte character is not valid. 

C0NF0RMST0 

SV ID 3, ISO 9899 

SEE ALSO 

mblen(3), mbstowcs(3), wcstombs(3), wctomb(3) 

GNU, 29 March 1993 


memccpy 

memccpy— C opies memory area 

SYNOPSIS 

#include <string.h> 

void *memccpy(void *dest , const void *src,int c, size_t n); 

DESCRIPTION 

Thememccpyo function copies no morethann bytes from memory area s r c to memory area dest , stopping when the 
character c isfound. 

RETURN VALUE 

Thememccpyo function returnsa pointer to thenext character in dest after c , or null if c was not found in thefirst n 
characters of s r c. 
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CONFORMSTO 

SVID 3, BSD 4.3 

SEE ALSO 

bcopy(3), memcpy(3), memmove(3), strcpy(3), strncpy(3) 

GNU, 10 April 1993 


memchr 

memchi — Scans memory for a character 

SYNOPSIS 

#include <string.h> 

void *memchr(const void *s,int c, size_t n); 

DESCRIPTION 

Thememchro function scansthe first n bytes of the memory area pointed to by s for the character c . The first byte to match c 
(interpreted as an unsigned character) stops the operation. 

RETURN VALUE 

Thememchro function returns a pointer to the matching byte or null if the character does not occur in the given memory 
area. 

CONFORMSTO 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

index(3), rindex(3), strchr(3), strpbrk(3), strrchr(3), strsep(3), strspn(3), strstr(3) 

GNU, 12 April 1993 


memcmp 

memcmp — C ompares memory areas 

SYNOPSIS 

#include <string.h> 

int memcmp(const void *sl, const void *s2, size_t n); 

DESCRIPTION 

The memcmp o function comparesthefirstn bytes of the memory areas si and s 2 . It returns an integer less than, equal to, or 
greater than zero if si isfound, respectively, to be less than, to match, or to be greater than s 2. 

RETURN VALUE 

The memcmp 0 function returns an integer less than, equal to, or greater than zero if thefirstn bytes of si isfound, respec¬ 
tively, to be less than, to match, or be greater than the first n bytes of s 2 . 



Part III: L ibrary Functions 


980 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

bcmp(3), strcasecmp(3), strcmp(3), strcoll(3), strncmp(3), strncasecmp(3) 

10 April 1993 


memcpy 

memcpy— Copies memory area 

SYNOPSIS 

#include <string.h> 

void ‘memcpy(void *dest , const void *src, size_t n); 

DESCRIPTION 

The memcpy o function copies n bytes from memory area s r c to memory area dest . The memory areas may not overlap. Use 
memmove(3) if the memory areas do overlap. 

RETURN VALUE 

The memcpy o function returns a pointer to dest. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

bcopy(3), memccpy(3), memmove(3), strcpy(3), strncpy(3) 

GNU, 10 April 1993 


memfrob 

memfrob— Frobnicates (encrypts) a memory area 

SYNOPSIS 

#include <string.h> 

void *memfrob(void *s, size_t n); 

DESCRIPTION 

Thememfrobo function encrypts the first n bytes of the memory areas by using exclusive or on each character with the 
number 42. The effect can be reversed by using memfrob o on the encrypted memory area. 

N otethat thisfunction isnot a proper encryption routine as thexoR constant isfixed, and isonly suitablefor hiding strings. 

RETURN VALUE 

Thememfrobo function returns a pointer to the encrypted memory area. 
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CONFORMSTO 

Thememfrobo function isuniquetotheLinuxC LibraryandGNU C Library. 

SEE ALSO 

strfry(3) 

GNU, 12 April 1993 

memmem 

memmem— Locatesa substring 

SYNOPSIS 

#include <string.h> 

DESCRIPTION 

The memmem o function fi nds the fi rst occurrence of the substring needi e of length needi el en in the memory area hay stack of 
length haystackl en. 

RETURN VALUE 

T he memmem) ) function returns a pointer to the beginning of the substring, or null if the substring is not found. 

SEE ALSO 

strstr(3) 

GNU, 11 April 1993 

memmove 

memmove— C opies memory area 

SYNOPSIS 

#include <string.h> 

void *memmove(void *dest , const void *src, size_t n); 

DESCRIPTION 

The memmove)) function copies n bytes from memory area s r c to memory area dest. The memory areas may overlap. 

RETURN VALUE 

The memmove)) function returns a pointer to des t. 

CONFORMSTO 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

bcopy(3), memccpy(3), memcpy(3), strcpy(3), strncpy(3) 


GNU, 10 April 1993 
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memset 

memset — Fills memory with a constant byte 

SYNOPSIS 

#include <string.h> 

void ‘memset(void *s,int c, size_t n); 

DESCRIPTION 

The memset o function fills the first n bytes of the memory area pointed to be s with the constant byte c . 

RETURN VALUE 

The memset o function returns a pointer to the memory areas. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

bzero(3), swab(3) 

GNU, 11 April 1993 


mkfifo 

mkfito — M akes a FI FO special file (a named pipe) 

SYNOPSIS 

#include <sys/types.h> 

//include <sys/stat.h> 

int mkfifo ( const char ‘pathname,mode_t mode ); 

DESCRIPTION 

mkfifo makes a FIFO special file with name pathname, mode specifies the FIFO's permissions It ismodified by the process's 
umask in the usual way: the permissions of the created file are (mode&umask). 

A FIFO special file is similar to a pipe, except that it is created in a different way. Instead of being an anonymous communi¬ 
cations channel, a FIFO special file is entered into thefilesystem by calling mkfifo. 

After you have created a FIFO special file in this way, any process can open it for reading or writing, in thesameway as an 
ordinary file. However, it has to be open at both ends simultaneously before you can proceed to do any input or output 
operations on it. 0 pening a FI FO for reading normally blocks until some other process opens the same FI FO for writing, 
and vice versa. 

RETURN VALUE 

The normal, successful return valuefrom mkfifo is e. In thecaseof an error, -i isreturned (in which case, errno isset 
appropriately). 


ERRORS 


EACCES 

EEXIST 


Oneofthedirectoriesin pathname did notallow search (execute) permission, 
pathname already exists 
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enametoolong Either the total length of pathname is greater than pathjiax, or an individual 

filename component has a length greater than name_max. IntheGNU system, 
thereisno imposed limit on overall filename length, but some filesystems may 
place limits on the length of a component. 

enoent A directory component in pathname does not exist or isa dangling symbolic 

link. 

enospc The directory or filesystem has no room for the new file. 

enotdir A component used as a directory in pathname is not, in fact, a directory. 

erofs pathname refersto a read-only filesystem. 

C0NF0RMST0 


SEE ALSO 

mkfifo(l), read(2), write(2), open(2), close(2), stat(2), umask(2) 


Linux 1.2.13,3 September 1995 


mkstemp 

mkstemp— C reates a unique temporary file 

SYNOPSIS 

#include <unistd.h> 

int *mkstemp(char ‘template); 


DESCRIPTION 

T he mkstemp () function generates a unique temporary filename from t e mp i a t e. T he last six characters of t e mp i ate must be 
xxxxxx and these are replaced with a string that makes the filename unique T hefile isthen created with mode read/write and 
permissions 0666. 


RETURN VALUE 

Themkstempo function returnsthefile descriptor fd of the temporary file 

ERRORS 

EINVAL 
EEXIST 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

mktemp(3), tmpnam(3), tempnam(3), tmpfile(3) 


T he last six characters of t empi ate were not xxxxxx. 
Thetemporary file is not unique. 


GNU, 3 April 1993 


mktemp 

mktemp- M akes a unique temporary filename 
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SYNOPSIS 

#include <unistd.h> 

char *mktemp(char 'template); 

DESCRIPTION 

Themktempo function generates a unique temporary filename from tempi ate. The last six characters of tempi ate must be 
xxxxxx and these are replaced with a string that makes the filename unique 

RETURN VALUE 

Themktempo function returns a pointer to tempi ate on success, and null on failure. 

ERRORS 

einval T he last six characters of template were not xxxxxx. 

C0NF0RMST0 

BSD 4.3. POSIX dictates tmpnamo. 

SEE ALSO 

mkstemp(3), tmpnam(3), tempnam(3), tmpfile(3) 

GNU, 3 April 1993 


modf 

modf — Extracts signed integral and fractional values from floating-point number 

SYNOPSIS 

#include <math.h> 

double modf (double x, double *iptr); 

DESCRIPTION 

T he modf o function breaks the argument x into an integral part and a fractional part, each of which has the same sign asx. 
Theintegral part isstored in i ptr. 

RETURN VALUE 

T he modf o function returns the fractional part of x. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

frexp(3), ldexp(3) 

6Junel993 


asctime, ctime, difftime, gmtime, localtime,mktime 

asctime, ctime, dif ftime, gmtime, localtime, mktime— C Onvert date and time to ASC11 



asctime, dime, difftime, gmtime localtime mktime 
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SYNOPSIS 

extern char *tzname[2]; 
void tzset() 

#include <sys/types.h> 
char *ctime(clock) 

double difftime(time1, time0) 

#include <time.h> 

char ‘asctime(tm) 
const struct tm *tm; 

struct tm ‘localtime(clock) 

struct tm ‘gmtime(clock) 

time_t mktime(tm) 
struct tm *tm; 

cc ... -lz 

DESCRIPTION 

ctime converts a long integer, pointed to by clock, representing the time in seconds since 00:00:00 UTC, January 1,1970, 
and returnsa pointer to a 26-character string of theform Thu Nov 24 18:22:48 1 986. (Note: UTC is Coordinated Universal 
Time.) All the fields have constant width. 

localtime and gmtime return pointers to tm structures, described in thefollowing paragraphs localtime corrects for the time 
zone and any time zone adjustments (such asDaylight SavingTimein theUnited States). Before doing so, localtime calls 
tzset (if tzset has not been called in the current process). After filling in thetm structure, localtime sets the tm_isdst'th 
element of tzname to a pointer to an ASCII string that's the time zone abbreviation to be used with locaitime's return value, 
gmtime converts to Coordinated Universal Time 

asctime convertsa time value contained in a tm structure to a 26-character string, as shown in the preceding example, and 
returns a pointer to the string. 

mktime converts the broken-down time expressed as local time, in the structure pointed to by tm into a calendar time value 
with thesame encoding as that of the values returned by the time function. The original values of the tm_wday and tm_yday 
components of the structure are ignored, and the original values of the other components are not restricted to their normal 
ranges. (A positive or zero value for tm_isdst causes mktime to presume initially that summer time (for example, Daylight 
SavingTimein theUnited States) respectively, isorisnot in effect for the specified time A negative value for tm_isdst 
causes the mktime function to attempt to divine whether summer time is in effect for the specified time.) On successful 
completion, the values of the tm_wday and tm_yday components of the structure are set appropriately, and the other 
components are set to represent the specified calendar time, but with their values forced to their normal ranges; the final 
value of tm_mday isnot set until tm_mon and tm_year are determined, mktime returnsthe specified calendar time; if the calendar 
time cannot be represented, it returns-i. 
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difftime returnsthedifference between two calendar time, (timei - ti me o), expressed in seconds. 

Declarations of all the functions and externals, and thetm structure, are in the <time.h> header file The structure (of type) 
struct tm includes thefollowing fields: 


int tm_yday; 
int tm_isdst; 
char tm_zone; 
long tm_gmtoff; 


/ seconds (0 - 60) / 

/ minutes (0 ■ 59) / 

/ hours (0 - 23) / 

/ month of year (0 - 11) / 

/ year - 1900 / 

/ day of week (Sunday = 0) / 

/ day of year (0 ■ 365) / 

/ is summer time in effect? / 

/ abbreviation of timezone name / 
/ offset from UTC in seconds / 


The tm_zone and tm_gmtoff fiddsexist, and are filled in, only if arrangements to do so were made when the library containing 
these functions was created. There is no guarantee that these fidds will continue to exist in this form in future rdeases of this 
code. 


Tm_isdst is non-zero if summer time is in effect. 

Tm_gmtoff isthe offset (in seconds) of the time represented from UTC, with positive values indicating east of the Prime 
Meridian. 


FILES 

/usr/local/etc/zoneinfo 
/usr/local/etc/zoneinfo/localtime 
/usr/local/etc/zoneinfo/posixrules 
/usr/local/etc/zoneinfo/GMT 


Time zone information directory 
Local ti me zonefile 
Used with POSIX-styleTZs 
For UTC leap seconds 


If /usr/local/etc/zoneinfo/GMT is absent, UTC leap Seconds are loaded from /usr/local/etc/zoneinfo/posixrules. 


SEE ALSO 

getenv(3), newtzset(3), time(2), tzfile(5) 


NOTES 

The return values point to static data; the data is overwritten by each call. The tm_zonefidd of a returned struct tm points to 
a static array of characters, which will also be overwritten at the next call (and by callsto tzset). 

Avoid using out-of-range values with mktime when setting up lunch with promptness sticklers in Riyadh. 


tzset 

tzset— I nitializes time conversion information 

SYNOPSIS 


3id tzset(); 
; ... -lz 





987 


tzset 


DESCRIPTION 

tzset uses the value of the environment variable tz to set time conversion information used by locaitime.lf tz does not 
appear in the environment, the best available approximation to local wall clock time, as specified by thetzftie(5)-format file 
locaitime in the system time conversion information directory, isused by locaittme. If tz appearsin the environment but its 
value is a null string, Coordinated Universal Time(UTC) isused (without leap second correction). If tz appearsin the 
environment and its value is not a null string, it is used in one of thefollowingways: 

If the value begins with a colon, it is used as a pathname of a file from which to read thetime conversion information. 

If the value does not begin with a colon, it isfirst used as the pathname of a file from which to read the time conversion 
information, and, if that file cannot be read, isused directly as a specification of the time conversion information. 

When tz isused asa pathname if it begins with a slash, it is used as an absolute pathname; otherwise, it is used asa 
pathname relative to a system time conversion information directory. The file must be in the form at specified in tzfiie(5). 

W hen tz isused directly as a specification of the time conversion information, it must have the following syntax (spaces 
inserted for clarity): 


The elements are as follows 

std anddst 


T hree or more bytes that are the designation for the standard (st d) or 
summer(dst)timezoneOnlystd is required; if dst is missing, then 
summer ti me does not apply i n this locale U ppercase and lowercase 
letters are explicitly allowed. Any characters except a leading colon (:), 
digits comma (,), minus (■), plus (+), and ASCII N U L are allowed. 
Indicates the value one must add to the local time to arrive at 
Coordinated Universal Time Theoff set has the form: 
h h[:mm[: s s ] ] 

The minutes W and seconds(ss) are optional. The hour (hh) isrequired 
and may be a single digit. The of f s et following st d isrequired. If no 
offset follows ds t, summer time is assumed to be one hour ahead of 
standard time. One or more digits may be used; the value is always 
interpreted as a decimal number. The hour must be between zero and 24, 
and the minutes (and seconds)— if present— between zero and 59. If 
preceded by a “+■, the time zone shall be east of the Prime Meridian; 
otherwise it shall be west (which may be indicated by an optional 
preceding "-■). 

Indicates when to change to and back from summertime. Therui e has 
theform: 


where the fi rst d a t e describes when the change from standard to summer 
ti me occurs and the second date descri bes when the change back happens. 
Each t i me field describes when, in current local time, thechangeto the 
other time is made 

The format of d a t e is one of the followi ng: 

Thed'th day (0 <=d <=6) of week n of month m of the year (1 <^n 
<=5,1 <=m <s= 12, where week 5 means "the last d day in month m" 
which may occur in either the fourth or thefifth week). Week 1 
is the first week in which thed'th day occurs Day zero is Sunday. 
Thejulian dayn (1 <=n <= 365). Leap days are not counted; that is, in 
all years- including leap years- February 28 is day 59 and M arch 1 is 
day 60. Itis impossible to explicitly refer to the occasional February 29. 
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n The zero-based Julian day (0 <=n <= 365). Leap days are counted, and it 

is possible to refer to February 29. 

Mm. n.d Thed'th day (0 <=d <=6) of week n of month m of the year (1 <=n <=5, 

1 <=m <= 12, where week 5 means "the last d day in month m," which 
may occur in either the fourth orthefifth week). Week 1 isthefirst week 
in which thed'th day occurs Day zero is Sunday. 

The time has the same format as offset except that no leading sign ("+" 
oris allowed. The default, if time is not given, is 02:00:00. 

If no rule is present in tz, the rules specified by the tzfiie(5)-format file posixruies in the system time conversion 
information directory are used, with the standard and summer time offsets from UTC replaced by those specified by the 
offset values in tz. 

For compatibility with System V Release 3.1, a semicolon (;) may be used to separate the rule from the rest of the specifica¬ 
tion. 

If the tz environment variable does not specify a tzfiie(5)-format and cannot be interpreted as a direct specification, UTC is 
used. 


FILES 

/usr/local/etc/zoneinfo 
/usr/local/etc/zoneinfo/localtime 
/usr/local/etc/zoneinfo/posixrules 
/usr/local/etc/zoneinfo/GMT 


Time zone information directory 
Local timezonefile 
Used with POSIX-style tzs 
For UTC leap seconds 


If /usr/local/etc/zoneinfo/GMT is absent, UTC leap Seconds are loaded from /usr/local/etc/zoneinfo/posixrules. 

SEE ALSO 

getenv(3), newctime(3), time(2), tzfile(5) 


on_exit 

on exit— Registers a function to be called at normal program termination 

SYNOPSIS 

//include <stdlib.h> 

int on_exit(void (‘function)(int , void *), void *arg); 

DESCRIPTION 

Theon_exit() function registers the given function to be called at normal program termination, whether via exit(2) or via 
return from the program's main. The function ispassed the argument to exit(3) and thearg argumentfrom on_exit(). 

RETURN VALUE 

Theon_exit() function rdturnsthe value 0 if successful; otherwise, the value-1 isreturned. 

SEE ALSO 

exit(3), atexit(3) 


GNU, 2 April 1993 
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opendir 

opendir— 0 pens a directory 

SYNOPSIS 


//include <sys/types.h> 



DESCRIPTION 

The opendir)) function opens a directory stream corresponding to the directory name and returns a pointer to the directory 
stream. The stream ispositioned at thefirst entry in the directory. 

RETURN VALUE 

The opendir)) function returns a pointer to the directory stream or null if an error occurred. 

ERRORS 

eacess Permission denied 

emfile Too many file descriptors in use by process 

enfile Too many files are currently open in the system 

enoent Directory does not exist, or name is an empty string 

enomem Insufficient memory to complete the operation 

enotdir name is not a directory 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3 

SEE ALSO 

open(2), readdir(3), closedir(3), rewinddir(3), seekdir(3), telldir(3), scandir(3) 

11Junel995 

parsedate 

parsedate— Converts time and date string to number 

SYNOPSIS 

//include <sys/types.h> 
typedef struct_TIMEINFO f 



DESCRIPTION 

parsedate converts many common time specifications into the number of seconds since the epoch, that is, a time_t; see 

time(2). 
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parsedate returnsthetime, or -i on error, text isacharacterstringcontainingthetimeand date now isa pointer to the time 
that should be used for calculating relative dates. If now is null, then GetTimeinfo in nbinn(3) is used to obtain the current 
time and time zone. 

The character string consists of zero or more specifications of the following form: 

time A time of day, which is of the form hh[:mm[:ss ]] [meri di an ] [zone ]Or hhmm 

[ me r i d i a n ] [z one ]. If no meridian isspecified, hh is interpreted on a24-hour 
clock. 

date A specific month and day with optional year. The acceptable formats are 

mm/dd [/ yy ], yyyy /mm/dd, mont hname dd[, yy],dd monthname [y y ] , and 
day.ddmonthnameyy, and day, dd monthname yy. T he default year isthecurrent 
year. If the year is less then 100, then 1900 is added to it; if it is less then 21, 
then 2000 is added to it. 

relative time A specification relativetothecurrenttime.Theformat isnumber unit; 

acceptable units are year, month, week, day, hour, minute (ormin), and second 
(or sec). The unit can be specified as a singular or plural, as in 3 weeks. 

T he actual date is calculated according to the following steps. First, any absolute date or time is processed and converted. 
Using that time as the bases, day-of-week specifications are added. Next, relative specifications are used. If a date or day is 
specified, and no absolute or relative time is given, midnight is used. Finally, a correction is applied so that the correct hour 
of the day is produced after allowing for D aylight Savings Time differences. 

parsedate ignores case when parsing all words; unknown words are taken to be unknown time zones, which are treated as 
GMT. The names of the months and days of the week can be abbreviated to their first three letters, with optional trailing 
period. Periods are ignored in anytimezoneor meridian values 

BUGS 

parsedate does not accept all desirable and unambiguous constructions Semantically incorrect dates such as"February 31" 
are accepted. 

D aylight Savings Time is always taken as a one-hour change that is wrong for some places The D aylight SavingsTime 
correction can get confused if parsing a time within an hour of when the reckoning changes or if given a partial date. 

HISTORY 

O riginally written by Steven M . Bellovin (smb@research. att. com) while at the U ni versity of N orth C arolina at C hapel Hill 
and distributed under the name getdate. 

A major overhaul wasdoneby Rich $alz (rsaiz@bbn.com) and Jim Berets (jberets@bbn.com) in August, 1990. 

It was further revised (primarily to remove obsolete constructs and time zone names) a year later by Rich (now 
rsaiz@osf.org) for I nterN etN ews and the name was changed. 

SEE ALSO 

date(l), ctime(3), libinn(3), time(2) 

pernor 

perror— Printsa system error message 

SYNOPSIS 

#include <stdio.h> 

void perrorfconst char *s); 

#include <errno.h> 
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const char *sys_errlist[]; 


DESCRIPTION 

The routine perror( ) produces a message on the standard error output, describing the last error encountered during a call to 
a system or library function. The argument string s isprinted first, then a colon and a blank, then the message and a newline. 
To be of most use, the argument string should include the name of the function that incurred theerror. Theerror number is 
taken from the external variable e r r n o , which issdt when errors occur but not cleared when nonerroneous calls are made. 
Theglobal error list sys_enriist[] indexed by err no can be used to obtain theerror message without the newline The largest 
message number provided in the table is sys_nerr -i. Be careful when directly accessing this list because new error values 
may not have been added to sys_e rriist [ ]. 

When a system call fails, it usually returns-i and sets the variable err no to a value describing what went wrong. (These values 
can be found in <errno.h>.) M any library functions do likewise. The function perroro serves to translate this error code into 
human-readableform. N otethat er r no is undefined after a successful library call. Thiscall may well change this variable 
even though it succeeds, for example because it internally used some other library function that failed. Thus, if a failing call 
is not immediately followed by a call to perror.the value of err no should be saved. 

C0NF0RMST0 

ANSI C, BSD 4.3, POSIX.X/OPEN 

SEE ALSO 

strerror(3) 

16 May 1996 


popen,pclose 

popen, pciose— Process I/O 

SYNOPSIS 

#include <stdio.h> 

FILE *popen(const char 'command, const char 'type); 
int pclose(FILE 'stream); 

DESCRIPTION 

T he popen o function opens a process by creating a pipe, forking, and invoking the shell. Because a pipe is by definition 
unidirectional, the type argument may specify only reading or writing, not both; the resulting stream is correspondingly 
read-only or write-only. 

The command argument is a pointer to a null-terminated string containing a shell command line. This command is passed to 
/bin/sh using the -c flag; interpretation, if any, is performed by the shell. Themode argument is a pointer to a null- 
terminated string which must be either r for reading or w for writing. 

The return value from popeno isa normal standard I/O stream in all respects save that it must be closed with pcioseo rather 
than fciose(). Writing to such a stream writes to the standard input of the command; the command's standard output is the 
same as that of the process that cal led popeno, unlessthis is altered bythecommand itself. Conversely, reading from a 
"popened" stream reads the command's standard output, and the command's standard input is the same as that of the 
process that called popen. 
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N otethat output popen streams are fully buffered by default. 

The pciose function waits for the associated process to terminate and returns the exit status of the command as returned by 

RETURN VALUE 

The popen function returns null if the fork(2) or pipe(2) calls fail, or if it cannot allocate memory. 

The pciose function returns -i if stream isnot associated with a"popened" command, if stream already "pdosed," or if warn 
returns an error. 

ERRORS 

The popen function does not reliably set e r r n o . (I s this true for L inux?) 

BUGS 

The standard input of a command opened for reading shares its seek offset with the process that called popeno; therefore, if 
the original process has done a buffered read, the command's input position may not be as expected. Similarly, the output 
from a command opened for writing may become intermingled with that of the original process The latter can be avoided 
by calling mush(3) before popen. 

Failure to execute the shell Isindistinguishablefrom theshdl's failure to execute command, or an immediate exit of the 
command. The only hint is an exit status of 127. (Is this true under Linux?) 

The function popeno always calls sh, never calls csh. 

HISTORY 

A popeno and a pciose o function appeared inversion 7 AT&T UNIX. 

SEE ALSO 

fork(2), sh(l), pipe(2), wait4(2), fflush(3), fclose(3), fopen(3), stdio(3), system(3), fclose(3), fopen(3), stdio(3), system(3). 

BSD man page, 17May 1996 

printf,fprintf, sprintf, snprintf, vprintf, vfprintf, 
vsprintf, vsnprintf 

printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf— Formatted Output Conversion 

SYNOPSIS 

#include <stdio.h> 

int printf( const char *format, ...); 

int fprintf) FILE ‘stream, const char ‘format, ...); 

int sprintf) char *str, const char ‘format, ...); 

int snprintf) char *str, size_t size, const char ‘format, ...); 

ffinclude <stdarg.h> 

ant vfprintf) FILE ‘stream, const char *for mat ,va_list ap); 

int vsprintf) char *str, char ‘format, va_list ap); 

int vsnprintf) char *str, size_t size, char *for mat ,va_list ap); 
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DESCRIPTION 

The printf family of functions produces output accordi ng to a f o r ma t , as described i n the following paragraphs The 
functions printf and vprintf write output to stdout, the standard output stream; fprintf and vfprintf write output to the 
given output stream; sprintf, snprintf, vsprintf, and vsnprintf write to the character String s t r. 

T hese functions write the output under the control of a f o r ma t string that specifies how subsequent arguments (or arguments 
accessed via the variable-length argument facilities of stdarg(3)) are converted for output. 

These functions return the number of characters printed (not including the trailing \o used to end output to strings), 
snprintf and vsnprintf do not write more than s'zebytes(including thetrailing \@),and return -i if the output was 
truncated due to this limit. 

Thef or mat string is composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the 
output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments Each 
conversion specification is introduced by the character %. The arguments must correspond properly (after type promotion) 
with the conversion specifier. After the%, zero or more of the following flags appear in sequence: 

# Specifying that the value should be converted to an alternate form. Fore, d, i, n, p, s, and u 

conversions, this option has no effect. For o conversions, the precision of the number is increased to 
force the first character of the output string to a zero (except if a zero value is printed with an explicit 
precision of zero). For x and x conversions a non-zero result has the string ex (or ex for x 
conversions) prepended to it. Fore, e, f, g, and g conversions, the result will always contain a decimal 
point, even if no digits follow it (normally, a decimal point appears in the results of those conversions 
only if a digit follows). For g and g conversions, trailing zeros are not removed from the result as they 
would otherwise be. 

0 Specifying zero padding. For all conversions except n, the converted value is padded on the left with 

zeros rather than blanks If a precision is given with a numeric conversion (d, i, o, u, i, x, and x), the 
0 flag is ignored. 

(a negative field width flag) Indicates the converted value is to be left adjusted on the field boundary. 
Except for n conversions the converted value is padded on the right with blanks rather than on the 
left with blanks or zeros A - overrides a 0 if both are given. 

1 1 (a space) Specifying that a blank should be left before a positive number produced by a signed 
conversion (d, e, e, t, g, g, or i). 

+ Specifying that a sign always be placed before a number produced by a signed conversion. 

A + overrides a space if both are used. 

1 Specifying that in a numerical argument the output is to be grouped if the locale information 

indicates any. Note that many versions of gcc cannot parse this option and will issueawarning. 

An optional decimal digit string specifying a minimum field width. If the converted value hasfewer 
characters than the field width, it will be padded with spaces on the left (or right, if the left- 
adjustment flag has been given) to fill out the field width. 

An optional precision, in the form of a period (.) followed by an optional digit string. If the digit 
string is omitted, the precision is taken as zero. This gives the minimum number of digits to appear 
fora, i, 0 , u, x, and x conversions; the number of digits to appear after the decimal point for e, e, and 
f conversions; the maximum number of significant digits for g and g conversions; or the maximum 
number of characters to be printed from a string for s conversions 

The optional character h, specifying that a following d, i, 0 , u, x, or x conversion corresponds to a 
short int or unsigned short int argument, or that a following n conversion corresponds to a pointer 
to a short int argument. 

The optional character 1 (ell) specifying that a following d, i, 0 , u, x, or x conversion applies to a 
pointer to along int or unsigned long int argument, or that a following n conversion corresponds to 
a pointer to a long int argument. Linux provides a non-AN Sl-compliant use of two 1 flags asa 
synonym to q or l. Thus 11 can be used in combination with float conversions. Thisusageis 
however, strongly discouraged. 
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The character l specifying that a following e, e, f, g, or g conversion corresponds to along double 
argument, or a following d, i, o, u, x, or x conversion corresponds to a long long argument. N otethat 
long long is not specified in AN SI C and therefore not portable to all architectures. 

Theoptional character q. This is equivalent to l. See the "Standards" and "Bugs" sectionsfor 
comments on the use of 11, l, and q. 

A z character specifying that the following integer (d, i, o, u, i, x, and x) conversion corresponds to a 
size_t argument. 

A character that specifies the type of conversion to be applied. 

A field width or precision, or both, may be indicated by an asterisk * instead of a digit string. In thiscase, an int argument 
supplies the field width or precision. A negative field width is treated as a left adjustment flag followed by a positive field 
width; a negative precision istreated as though it were missing. 

The conversion specifiers and their meanings are as follows: 

diouxx The int (or appropriate variant) argument is converted to signed decimal (d and i), 

unsigned octal (o), unsigned decimal (u), or unsigned hexadecimal (x and x) notation. The 
letters abcdef are used for x conversions; the letters abcdef are used for x conversions. T he 
precision, if any, gives the minimum number of digits that must appear; if the converted 
value requires fewer digits, it is padded on the left with zeros. 
eE The double argument isrounded and converted in the style [-]d.ddde\dd where there is 

onedigit before the decimal-point character and the number of digits after it is equal 
to the precision; if the precision is missing, it istaken as 6; if the precision is zero, no 
decimal-point character appears. An e conversion uses the letter e (rather than e) to 
introduce the exponent. The exponent always contains at least two digits; if the value is 
zero, the exponent is 00. 

f The double argument isrounded and converted to decimal notation in the style 

I - jddd. ddd, where the number of digits after the decimal-point character is equal to 
the precision specification. If the precision is missing, it is taken as6; if the precision is 
explicitly zero, no decimal-point character appears. If a decimal point appears at least one 
digit appears before it. 

9 The double argument is converted in style f ore (or e for g conversions). The precision 

specifies the number of significant digits If the precision is missing, 6 digits are given; if 
the precision is zero, it istreated asl. Style e is used if the exponent from its conversion is 
less than negative 4 or greater than or equal to the precision. Trailing zeros are removed 
from the fractional part of the result; a decimal point appears only if it isfollowed by at 
least one digit. 

c The int argument is converted to an unsigned char, and the resulting character is written, 

s T he char * argument is expected to be a pointer to an array of character type (pointer to a 

string). Characters from the array are written up to (but not including) a terminating nul 
character; if a precision isspecified, no more than the number specified are written. If a 
precision is given, no null character need be present; if the precision is not specified, oris 
greater than the size of the array, the array must contain a terminating nul character, 
p Thevoid ‘ pointer argument isprinted in hexadecimal (asif by %#xor%#ix). 

n The number of characters written so far is stored into the integer indicated bytheint * 

(or variant) pointer argument. N o argument is converted. 

% A % is written. No argument is converted. The complete conversion specification is%%. 

In no case does a nonexistent or small field width cause truncation of afield; if the result of a conversion iswider than the 
field width, the field is expanded to contain the conversion result. 
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EXAMPLES 

To print a date and time in theform "Sunday, J uly 3,10:02," where weekday and 



To print to five decimal places: 


: pointers to strings 




fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0) 

To allocate a 128-byte string and print into it: 



SEE ALSO 

printf(l), scanf(3) 

STANDARDS 

The fprintf, printf, sprintf, vprintf, vfprintf, and vsprintf functions conform to AN SI C 3.159-1989 ("AN SI C"). 

T he q flag is the BSD 4.4 notation for long long, while 11 or the usage of l in integer conversions is theGN U notation. 

The Linux version of these functions is based on theGN U libio library. T ake a look at the inf o documentation of GN U 
libc (glibc-1.08) for a more concise description. 

BUGS 

Some floating point conversions under Linux cause memory leaks. 

All functions are fully AN SI C 3.159-1989 conformant, but provide the additional flags q, z, and 1 as well as an additional 
behavior of the l and i flags T he latter may be considered to be a bug, as it changes the behavior of flags defined in AN SI 
C 3.159-1989. 

The effect of padding the %p format with zeros (either by the 0 flag or by specifying a precision), and the benign effect (that 
is, none) of the # flag on %n and %p conversions, as wel I as nonsensical combinationsthat are not standard; such combinations 
should be avoided. 

Some combinations of flags defined by A N SI C are not making sense (for example, %Ld). While they may have a well-defined 
behavior on Linux, this need not to be so on other architectures Therefore, it usually is better not to use flags that are not 
defined by AN SI C at all; in other words, that use q instead of Lin combination with diouxx con versions or 11. 

The usage ofq is not the same ason BSD 4.4, as it may be used in float conversions equivalently to l. 
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Because sprintf and vsprintf assume an infinitely long string, callers must be careful not to overflow the actual space; this is 
often impossible to assure 

Linuxman paget 28January 1996 


psignal 

psignai-Prints signal message 

SYNOPSIS 

#include <signal.h> 

void psignal(int sig, const char *s); 

extern const char *const sys_siglist[] 


DESCRIPTION 

The psignai)) function displays a message on stderr consisting of the strings, a colon, a space, and a string describing the 
signal number sig. If sig isinvalid, the message displayed will indicate an unknown signal. 

The array sys sigiist holds the signal description strings indexed by signal number. 

RETURN VALUE 

The psignaio function returns no value 

C0NF0RMST0 

BSD 4.3 


SEE ALSO 

perror(3), strsignal(3) 


GNU, 13 April 1993 


putenv 

putenv—Changes or adds an environment variable 

SYNOPSIS 

#include <stdlib.h> 

int putenv(const char ‘string); 

DESCRIPTION 

The putenv)) function adds or changesthe value of environment variables. The argument string is of the form name = value. 
If name does not already exist in the environment, then string is added to theenvironment. If name does exist, then the value 
of name in the environment is changed to vai ue. 

RETURN VALUE 

The putenv)) function returns zero on success, or-i if an error occurs 

ERRORS 


ENOMEM 


Insufficient space to allocate new environment 
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CONFORMSTO 

SVID 3, POSIX, BSD 4.3 

SEE ALSO 

getenv(3), setenv(3), unsetenv(3) 

GNU, 8 April 1993 

putpwent 

putpwent— W rites a password file entry 

SYNOPSIS 

//include <pwd.h> 

#include <stdio.h> 

#include <sys/types.h> 

int putpwent(const struct passwd * p,FILE*stream); 

DESCRIPTION 

The putpwent o function writes a password entry from the structure p in the file associated with stream. 

The passwd structure is defined in <pwd.h> as follows: 
struct passwd { 



RETURN VALUE 

The putpwent o function returns 0 on success, or -1 if an error occurs. 

ERRORS 

einval Invalid (null) argument given 

CONFORMSTO 

SVID 3 

SEE ALSO 

fgetpwent(3), getpwent(3), setpwent(3), endpwent(3), getpwnam(3), getpwuid(3), getpw(3) 

GNU, 9 April 1993 

fputc, f puts, putc, putchar, puts 

fputc, fputs, putc, putchar, puts— 0 utput of characters and strings 
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SYNOPSIS 

#include <stdio.h> 

int fputc(int c,FILE'Stream); 

int fputs(const char *s,FILE*st ream); 

int putc(int c.FILE ‘stream); 

int putchar(int c ); 

int puts(char *s); 

int ungetc(int c.FILE ‘stream); 

DESCRIPTION 

fputco writes the character c, cast to an unsigned char, to stream, 
fputso writes the string s to stream, without its trailing \b. 

putc () is equivalent to fputco except that it may be implemented as a macro that evaluates stream more than once. 

putchar(c ); is equivalent to putc(c,stdout). 

putso writes the strings and a trailing newlineto stdout. 

Calls to the functions described here can be mixed with each other and with calls to other output functions from thestdio 
library for the same output stream. 

RETURN VALUES 

fputco, putco, and putcharo return the character written as an unsigned char cast to an int orEOF on error, 
putso and fputso return a non-negative number on success, or eof on error. 

C0NF0RMST0 

ANSI C.POSIX.1 

BUGS 

It is not advisable to mix calls to output functions from thestdio library with low-level calls to writeo for the file descriptor 
associated with thesameoutput stream; the results will be undefined and very probably not what you want. 

SEE ALSO 

write(2), fopen(3), fwrite(3), scanf(3), gets(3), fseek(3), ferror(3) 

GNU, 4 April 1993 


qio 

qio— Quick I/O part of I nterN etN ews library 

SYNOPSIS 

#include "qio.h" 

QIOSTATE * 

Q10open(name, size) 
char ‘name; 

QIOSTATE * Q10fdopen(fd, size) 
int fd; 

void QlOclose(qp) 

QIOSTATE *qp; 






char * QlOread(qp) 

QIOSTATE *qp; 
int QlOlength(qp) 

QIOSTATE *qp; 
int QlOtoolong(qp) 

QIOSTATE *qp; 
int QlOerror(qp) 

QIOSTATE *qp; 
int QlOtell(qp) 

QIOSTATE *qp; 
int QlOrewind(qp) 

QIOSTATE *qp; 
int QlOfileno(qp) 

QIOSTATE *qp; 

DESCRIPTION 

The routines described in this manual page are part of the InterNdtNews library, iibinn(3). They are used to provide quick 
read access to files The letters qio stand for Q uick I/O. 

Qioopen opens thefile name for reading. It usesa buffer of size bytes, which must also be larger then the longest expected line. 
The header file defines the constant qio_buffer as a reasonable default. If size iszero, then Qioopen will call stat(2) and use 
the returned block size; if that fails it will useQio_BUFFER. It returns null on error, or a pointer to a handle to be used in other 
calls Qiotdopen performs the same function except that fd refers to an already-open descriptor. 

Qiociose closes the open file and releases any resources used by it. 

Qioread returns a pointer to the next line in thefile The trailing newline will be replaced with a\e. If eof is reached, an error 
occurs, or if the line is longer than the buffer, aioread returns null. 

After a successful call to aioread, aioiength will return the length of the current line 

Thefunctionsoiotooiong and Qioerror can be called after Qioread returns null to determine if there was an error, or if the 
line was too long. If aiotooiong returns non-zero, then the current line did not fit in the buffer, and the next call to Qioread 
will try read the rest of the line Long lines can only be discarded. If Qioerror returns non-zero, then a serious I/O error 
occurred. 

Qioteii returns the iseek(2) offset at which the next line will start. 

Qiorewind sets the read pointer back to the beginning of the file 
Qiotiieno returns the descriptor of the open file 

Qioiength, Qiotooiong, Qioerror, Qioteii, and Qiotiieno are implemented as macros defined in the header file 

EXAMPLE 

QIOSTATE *h; 
long offset; 
char *p; 

h = QlOopen("/etc/motd", QIO_BUFFER); 

for (offset = QlOtell(h); (p = QlOread(h)) != NULL; offset = QlOtell(h)) 
printf("At %ld, %s\n", offset, p); 

If (QlOerror(h)) { 

exit(1); 

} 

QlOclose(h); 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 
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qsort 

qsort — Sorts an array 

SYNOPSIS 

#include <stdlib.h> 

void qsort(void ‘base, size_t nmemb, size_t size,int(*compar) 

DESCRIPTION 

The qsort o function sorts an array with nmemb elements of size si ze.The base argument points to the start of the array. 

The contents of the array are sorted in ascending order according to a comparison function pointed to by compar, which is 
called with two arguments that point to theobjects being compared. 

Thecomparison function must return an integer less than, equal to, or greater than zero if thefirst argument isconsidered to 
be respectively less than, equal to, or greater than thesecond. If two members compareas equal, their order in the sorted 
array is undefined. 

RETURN VALUE 

T he qsort o function returns no value. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

sort(1) 

GNU, 29 March 1993 


raise 

raise- Sends a signal to the current process 

SYNOPSIS 

#include <signal.h> 

DESCRIPTION 

The raise function sends a signal to the current process. It is equivalent to 
kill(getpid(),si g) 

RETURN VALUE 

Zero on success, non-zero for failure. 

C0NF0RMST0 

ANSI C 

SEE ALSO 

kill(2), signal(2), getpid(2) 


GNU, 31 August 1995 
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rand,srand 

rand, srand— Random number generator 

SYNOPSIS 

#include <stdlib.h> 
int rand(void); 

void srand(unsigned int seed); 

DESCRIPTION 

Therando function returns a pseudo-random integer between 0 and rand_max. 

The srand 0 function sets its argument as the seed for anew sequence of pseudo-random integers to be returned by rando. 
These sequences are repeatable by calling srand 0 with the same seed value. 

If no seed value is provided, therando function is automatically seeded with a value of 1. 

RETURN VALUE 

Therando function returns a value between 0 and randjiax. The srand 0 returns no value. 

NOTES 

The versions of rando and srand 0 intheLinuxC Library use the same random number generator as random 0 and 
srandomo, so the lower-order bits should be as random as the higher-order bits. H owever, on older rando implementations, 
the lower-order bits are much less random than the higher-order bits 

In Numerical Recipesin C:TheArtofSaentificComputing(\N\\\\am H. Press Brian P. Flannery, Saul A. Teukolsky, William 
T. V Sterling; New York: Cambridge University Press 1990, first ed, p. 207), thefollowing comments are made: 

"If you want to generate a random integer between land 10, you should always do itby 

j=1 + (int) (10.0*rand()/(RAND+MAX+1.0)); 

and never by anything resembling 
j=1+((int) (1 000000 .0*rand()) % 10); 

(which uses lower-order bits)." 

Random-number generation isacomplextopic.TheNumericai Recipes in ebook (see preceding reference) provides an 
excellent discussion of practical random-number generation issues in Chapter 7, "Random Numbers." 

For a more theoretical discussion that also covers many practical issues in depth, please see C hapter 3, "Random Numbers," 
in Donald E. K nuth's T he Art of C ompu ter Programming, Volume2 (Seminumerical Algorithms), 2nd ed.; Reading, 

M assachusetts: Addison-W esley Publishing Company, 1981. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

random(3), srandom(3), initstate(3), setstate(3) 

GNU, 18 May 1995 


random,srandom,initstate,setstate 

random, srandom, initstate, setstate— Random number generator 
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SYNOPSIS 

//include <stdlib.h> 

long int random(void); 

void srandom(unsigned int seed); 

char *initstate(unsigned int seed, char ‘state ,int n); 
char *setstate(char ‘state); 

DESCRIPTION 

The randomo function usesa nonlinear additive feedback random number generator employing a default table of size 31 long 
integers to return successive pseudo-random numbers in the range from oto rand_max. T he period of this random number 
generator is very large approximately 16*( (2**31 )-i). 

Thesrandomo function sets its argument astheseed for a new sequence of pseudo-random integers to be returned by 
random)). T hese sequences are repeatable by calling srandom () with the same seed value I f no seed value is provided, the 
random)) function is automatically seeded with a value of 1. 

Theinitstate)) function allows a state array state to be initialized for use by random 0. The size of the state array n is used by 
imtstateo to decide how sophisticated a random number generator it should use—the larger the state array, the better the 
random numbers will be. seed is the seed for the initialization, which specifies a starting point for the random number 
sequence, and provides for restarting at the same point. 

Thesetstateo function changes the state array used by the random)) function. The state array state is used for random 
number generation until the next call to imtstateo or setstate)). state must first have been initialized using initstate)). 

RETURN VALUE 

The random)) function returns a value between 0 and randjiax. The srandom)) function returns no value. Theinitstate)) 
and setstate)) functions return a pointer to the previous state array. 

ERRORS 

einval A state array of less than 8 bytes was specified to imtstate (). 

NOTES 

C urrent "optimal" valuesfor the size of the state array n are 8,32,64,128, and 256 bytes; other amounts will be rounded 
down to the nearest known amount. Using less than 8 bytes will cause an error. 

C0NF0RMST0 

BSD 4.3 


SEE ALSO 

rand(3), srand(3) 


GNU, 28 March 1993 


readdin 

readdir- Reads a directory 


SYNOPSIS 

//include <sys/types.h> 

//include <dirent.h> 

struct dirent *readdir(DIR *dir); 
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DESCRIPTION 

The readdiro function returns a pointer to a dirent structure representing the next directory entry in the directory stream 
pointed to by d i r . It returns null on reaching the end-of-file or if an error occurred. 

The data returned by readdiro isoverwritten by subsequent calls to readdiro for the same directory stream. 

According to PO SIX, the dirent structure contains a field char_d_name[] of unspecified size with at most name_max characters 
preceding the terminating null character. U se of other fields will harm the portability of your programs 

RETURN VALUE 

The readdiro function rdturnsa pointer to a dirent structure, or null if an error occursor end-of-file isreached. 

ERRORS 

ebadf I nvalid directory stream descriptor dir 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3 

SEE ALSO 

read(2), opendir(3), closedir(3), rewinddir(3), seekdir(3), telldir(3), scandir(3) 

22 April 1996 


readv,writev 

readv, writev— Readsor writesdata into multiple buffers 


SYNOPSIS 

#include <sys/uio.h> 

int readv(int filedes, const struct iovec ‘vector , 


DESCRIPTION 

The readv o function reads count blocksfromthefileassociated with thefiledescriptor f i i edes into the multiple buffers 
described by vector. 

Thewritevo function writesat most count blocks described by vector to the file associated with thefiledescriptor f i i edes. 
The pointer vector points to a struct iovec defined in <Sys/uio.h>as 



void ‘iovbase; /* Starting address */ 
size_t iov_len; /* Number of bytes */ 

} ; 

Buffers are processed in theorder vector^], vectorm, ... vector[count]. 

T he readv o function works just like read(2) except that multiple buffers are filled. 

Thewritevo function worksjust like write(2) except that multiple buffers are written out. 

RETURN VALUES 

T he readv o function returnsthe number of bytes or -i on error; thewritevo function returnsthe number of bytes written. 
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ERRORS 

The readv() and writevo functions can fail and set er r no to the following values: 
ebadf fd is not a valid file descriptor. 

einval fd is unsuitable for reading (for readvo) or writing (for writevo). 

efault but is outside the processes' address space 

eagain Nonblocking I/O had been selected in the open o call, and reading or writing could not be 

done immediately. 

eintr Reading or writing was interrupted before any data was transferred. 

C0NF0RMST0 

unknown 

BUGS 

It is not advisable to mix calls to functions like readvo or writevo, which operate on file descriptors, with thefunctions 
from the stdio library; the results will be undefined and probably not what you want. 

SEE ALSO 

read(2),write(2) 

GNU, 25 April 1993 


realpath 

reaipath— Returnsthecanonicalized absolute pathname 

SYNOPSIS 

#include <sys/param.h> 

#include <unistd.h> 

char *realpath(char ‘path, char resolved_pat h []) ; 


DESCRIPTION 

reaipath expands all symbolic links and resolves references to / ./,/../ and extra / characters in the null-terminated string 
named by path and stores the canonicalized absolute pathname in the buffer of sizewAXPATHLEN named by resoived_path. The 
resulting path will have no symbolic link, /. /, or /.. / components 

RETURN VALUE 

If there is no error, it returns a pointer to the resoived_path. 

Otherwise, it returns a null pointer and places in resoived_path the absolute pathname of the path component that could not 
be resolved. The global variablecrmo issdtto indicate the error. 


ERRORS 

ENOTDIR 

EINVAL 

ENAMETOOLONG 

ENOENT 

EACCES 

ELOOP 

EIO 


A component of the path prefix is not a directory. 

T he pathname contains a character with the high-order bit set. 

A component of a pathname exceeded maxnamlen characters, or an entire path 
name exceeded maxpathlen characters. 

T he named file does not exist. 

Search permission is denied for a component of the path prefix. 

T oo many symbolic links were encountered in translating the pathname 
An I/O error occurred while reading from thefilesystem. 



regcomp, regexec, regerror, regfree 


SEE ALSO 

readlink(2), getcwd(3) 


GNU, 29July 1994 


Re_comp, re_exec 

re_comp, re_exec-BSD regex functions 


SYNOPSIS 

#include <regex.h> 

char *re comp(char *r egex); 

int re exec(char ‘string); 

DESCRIPTION 

re_comp is used to compile the null-terminated regular expression pointed to by regex. The compiled pattern occupies a static 
area, the pattern buffer, which isoverwritten by subsequent use of re_comp. If regex is null, no operation is performed and 
the pattern buffer's contents are not altered. 

re_exec isused to assess whether the null-terminated string pointed to by string matches the previously compiled regex. 

RETURN VALUE 

re_comp returnsNULL on successful compilation of regex; otherwise it returnsa pointer to an appropriate error message 
re_exec returns i for a successful match, zero for failure. 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

regex(7), GNU regex manual 

Linux, 14 July 1995 


regcomp, regexec, regerror, regf ree 

regcomp, regexec, regerror, regfree— PO SIX regex functions 

SYNOPSIS 

#include <regex.h> 

int regcomp(regex_t *preg , const char ‘regex, int cflags); 

int regexec(const regex_t *p r e g , const char ‘string, size_t n ma t c h , regmatch_t pmatch[], int eflags); 
size_t regerror(int errcode, const regex_t *p r e g , char ‘errbuf, size_t errbuf_size); 
void regfree(regex_t *preg); 

POSIX REGEX COMPILING 

regcomp isused to compile a regular expression into a form that is suitable for subsequent regexec searches, 
regcomp is supplied with preg, a pointer to a pattern buffer storage area; regex, a pointer to the null-terminated string; and 
cf i a gs, flags used to determine the type of compilation. All regular expression searching must be done via a compiled pattern 
buffer; thus, regexec must always be supplied with the address of a regcomp initialized pattern buffer. 
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i g s may be the bitwise or of one or more of the following: 

UsePOSIX extended regular expression syntax when interpreting regex. If 
not set, PO SIX basic regular expression syntax is used. 

Do not differentiate case Subsequent regexec searches using this pattern 
buffer will be case-insensitive. 

Support for substring addressing of matches is not required. Then mat c h and 
p match parameters to regexec are ignored if the pattern buffer supplied was 
compiled with thisflag set. 

M atch-any-character operators don't match a newline A nonmatching list 
([-...]) not containing a newline matchesa newline. M atch-begin ning-of- 
line operator (-) matches the empty string immediately after a navline 
regardless of whether ef lags, the execution flags of regexec, contains 
reg_notbol. M atch-end-of-line operator ($) matches the empty string 
immediately before a newline, regardless of whether ef i a g s contains 

REG_N0TE0L. 

POSiX REGEX MATCHING 

regexec isused to match a null-terminated string against the precompiled pattern buffer, pr eg. nmatch and pmatch are used to 
provide information regarding the location of any matches, ef i ags may be the bitwise or of one or both of reg_notbol and 
reg_noteol, which cause changes in matching behavior described in thefollowing list. 

reg_notbol The match-beginning-of-lineoperator alwaysfailsto match (but seethe 

compilation flag regjiewline, in the preceding subsection). Thisflag may be used 
when different portions of a string are passed to regexec and the beginning of the 
string should not be interpreted as the beginning of the line. 
reg_noteol Thematch-end-of-lineoperator alwaysfailsto match (but seethecompilation 

flag reg_newline, in the preceding subsection). 

BYTE OFFSETS 

UnlessREG_NosuB was set for the compilation of the pattern buffer, it is possible to obtain substring match addressing 
information, pmatch must be dimensioned to have at I east n ma t c h elements. These are filled in by regexec with substring 
match addresses. Any unused structure elements will contain the value -i. 

The regmatch_t structure that is the type of pmatch isdefined in regex.h: 
typedef struct 
{ 

} regmatch_t; 

Each rm_so element that is not -i indicates the start offsdt of the next largest substring match within the string. The relative 
rm_eo element indicates the end offset of the match. 

POSIX ERROR REPORTING 

regerror isused to turn the error codes that can be returned by both regcompand regexec into error messagestrings 
regerror is passed the error code, e r r c o d e; the pattern buffer, pr eg; a pointer to a character stri ng buffer, er r but; and the size 
of the string buffer, errbuf_si ze. It returnsthesizeof theer r buf required to contain the null-terminated error message string. 
If both er r but and e r r buf _ s i ze are non-zero, er r buf isfilled in with thefirst errbuf_size - i characters of the error message 
and a terminating null. 






remove 


POSIX PATTERN BUFFER FREEING 

Supplying regfree with a precompiled pattern buffer, pr eg will free the memory allocated to the pattern buffer by the 
compiling process, regcomp. 

RETURN VALUE 

regcomp returns zero for a successful compilation or an error code for failure, 
regexec returns zero for a successful match or reg_nomatch for failure 


ERRORS 


Thefollowing errors can be returned by regcomp: 


REG_BADRPT 

REG_BADBR 

REG_EBRACE 

REG_EBRACK 

REG_ERANGE 

REG_ECTYPE 

REG_EPAREN 

REG_ESUBREG 

REG_EEND 

REG_ESCAPE 

REG_BADPAT 

REG_ESIZE 

REG_ESPACE 


Invalid use of repetition operators, such as using* as thefirst character 
I nvalid use of back reference operator 
U nmatched brace interval operators 
U nmatched bracket list operators 

I nvalid use of the range operator; for example, the ending point of the range 

occurspriorto thestarting point 

U nknown character class name 

U nmatched parenthesis group operators 

Invalid back reference to a subexpression 

N on-specific error 

Invalid escape sequence 

I nvalid use of pattern operators such as group or list 

Compiled regular expression requires a pattern buffer larger than 64Kb 

The regex routines ran out of memory 


C0NF0RMST0 

POSIX 


SEE ALSO 

regex(7), GNU regex manual 


Linux, 13 July 1994 


remove 

remove— Deletes a name and possibly the file to which it refers 

SYNOPSIS 

#include <stdio.h> 

int remove(const char ‘pathname); 

DESCRIPTION 

remove deletes a name from thefilesystem. If that name was the last link to a file and no processes have thefile open, the file 
isdeleted and thespaceit was using ismade available for reuse. 

If the name was the last link to a file but any processes still have thefile open, thefile will remain in existence until the last 
filedescriptor referring to it isclosed. 
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If the name referred to a symbolic link, the link is removed. 

If the name referred to a socket, fifo, or device, the name for it is removed, but processes that have the object open may 

continue to use it. 


RETURN VALUE 


0 n success, zero is returned. 0 n error, - 

i is returned, and errno is set appropriately. 

ERRORS 


EFAULT 

pat hname points outside your accessi ble address space. 

EACCES 

W rite access to the directory contai ningpat hname is not al lowed for the 
process's effective uid, or one of the directories in pathname did notallow search 
(execute) permission. 

EPERM 

Thedirectory containing pat hname hasthesticky-bit (s_isvtx) set and the 
process's effective uid is neither the uid of the file to be deleted nor that of the 
directory containing it. 

ENAMETOOLONG 

pathname WaStOO long. 

ENOENT 

A directory component in pat hname does not exist or isa dangling symbolic 
link. 

ENOTDIR 

A component used asa directory in pathname is not, in fact, a directory. 

EISDIR 

pathname refersto a directory. 

ENOMEM 

Insufficient kernel memory was available. 

EROFS 

p a t h n a me refers to a file on a read-only fi lesystem. 


CONFORMSTO 

SVID, AT&T, POSIX, X/OPEN , BSD 4.3 

BUGS 

Inadequacies in the protocol underlying N FS can cause the unexpected disappearance of files that are still being used. 

SEE ALSO 

unlink(2), rename(2), open(2), rmdir(2), mknod(2), mkfifo(3), link(2), rm(l), unlink(8) 

Linux, 13 July 1994 

res_query, res_search, resjnkquery, res_send, res_init, 
dn_comp, dn_expand 

nes_query, res_search, resjnkquery, res_send, res_init, dn_comp, dn_expand— Resolver routines 

SYNOPSIS 

#include <sys/types.h> 

#include <netinet/in.h> 

#include <arpa/nameser.h> 

#include <resolv.h> 

res_query(dname, class, type, answer, anslen) 
const char *dname; 






res_query, res_search, res_mkquery, res_send, res_init, dn_comp, dn_expand 


res mkquery(op, d n a me, 

const char *dname; 
int cl ass, type; 
const char *dat a; 




ansi en ) 


int length; 


I ength, 


u_char “dnpt rs, **lastdnptr; 


dn_expand(msg, eomorig, comp_dn, exp_dn, length) 
const u_char *msg, ‘eomorig, *comp_dn; 

hstrerror(int err); 


DESCRIPTION 


These routines are used for making, sending and interpreting query and reply messages with Internet domain name servers 


G lobal configuration and state information that is used by the resolver routines is kept in the structure_res. M ost of the 
values have reasonable defaults and can be ignored. Options stored in _res. options are defined in resoiv.h and are as 
follows. 0 ptions are stored as a simple bit mask containing the bitwise or of the options enabled. 


RES_INIT 

RES_DEBUG 

RES_AAONLY 


RES_USEVC 

RES_STAYOPEN 


RES_IGNTC 

RES_RECURSE 


T rue if the initial nameserver address and default domain name are 
initialized (that is, res_imt has been called). 

Print debugging messages 

Accept authoritative answers only. With this option, res_send should 
continue until it finds an authoritative answer or finds an error. 

C urrently, this is not implemented. 

UseTCP connections for queries instead of U D P datagrams. 

Used with res_usevc to keep the TCP connection open between queries. 
This is useful only in programs that regularly do many queries. U D P 
should be the normal mode used. 

Unused currently (ignore truncation errors-don't retry with TCP). 

Set the recursion-desired bit in queries This isthe default. (res_send does 
not do iterative queries and expects the nameserver to handle recursion.) 
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If sdt, res_search will append the default domain name to single¬ 
component names (those that do not contain a dot). Thisoption is 
enabled by default. 

If thisoption is set, res_search will search for hostnames in the current 
domain and in parent domains; see hostname(7). This is used by the 
standard host lookup routine gethostbyname(3). Thisoption isenabled 
by default. 

Thisoption turns off the user level aliasing feature controlled by the 
hostaliases environment variable. N dtwork daemonsshould sdt this 
option. 

The res_init routine reads the configuration file (if any; see resoiver(5)) to get the default domain name, search list and the 
Internet address of the local nameserver(s). If no server isconfigured, the host running the resolver is tried. The current 
domain nameisdefined by the hostname if not specified in theconfiguration file; it can be overridden by the environment 
variable localdomain. This environment variable may contain several blank-separated tokens if you wish to override the 
search list on a per-process basis. This is similar to the search command in theconfiguration file. Another environment 
variable (res_options) can besdtto override certain internal resolver options that are otherwise set by changing fields in the 
_res structure or are inherited from theconfiguration file's options command. T he syntax of the res_options environment 
variable is explained in resoiver(5). Initialization normally occurs on the first call to one of the other resolver routines 
The res_query function provides an interface to the server query mechanism. It constructs a query, sends it to the local 
server, awaits a response and makes preliminary checkson the reply. Thequery requests information of the specified type 
and class for the specified fully-qualified domain named name. The reply message is left in the answer buffer with length 
ansi en supplied by the caller. 

The res_search routine makes a query and awaits a response like res_query, but in addition, it implements the default and 
search rules controlled by the res_defnames and res_dnsrch options. It returns the first successful reply. 

The remaining routines are lower-level routines used by res_query. The resjnkquery function constructs a standard query 
message and places it in buf. It returnsthe size of thequery, or-i if the query is larger than bufien. The query type o p is 
usually query, but can be any of the query types defined in <arpa/nameser.h>. The domain name for the query is given by 
dname. Newrr is currently unused but is intended for making update messages 

The res_send routine sends a preformatted query and returns an answer. It will call res_imt if res_init isnotsdt, send the 
query to the local nameserver, and handle time-outs and retries T he length of the reply message is returned, or-i if there 
were errors 

T he dn_comp function compresses thedomain nameexp_dn and stores it in comp_dn.Thesizeof thecompressed name is 
returned or-i if there were errors. The size of the array pointed to by comp_dn isgiven by length. The compression uses an 
array of pointers dnptrs to previously-compressed namesin thecurrent message. The first pointer points to the beginning of 
the message and the list ends with null. The limit to the array isspecified by lastdnptr. A side effect of dn_comp is to update 
the list of pointers for labels inserted into the message as the name is compressed. If dnptr is null, names are not compressed. 
If lastdnptr isNULL, the list of labels is not updated. 

Thedn_expand entry expands the compressed domain name comp_dn to a full domain name. Thecompressed nameis 
contained in a query or reply message; msg isa pointer to the beginning of the messagaThe uncompressed name is placed in 
the buffer indicated by exp_dn, which is of size length. The size of compressed name is returned or -i if there was an error. 




FILES 



rint 


SEE ALSO 

gethostbyname(3), named(8), resolver(5), hostname(7), 
RFC1032, RFC 1033, RFC1034, RFC1035, RFC974 
SM M : 11 Name Server Operations Guide for BIN D 


11 December 1995 


rewinddir 

rewinddir- Resets directory stream 


SYNOPSIS 

#include <sys/types.h> 

#include <dirent.h> 
void rewinddir(DIR *dir); 

DESCRIPTION 

The rewinddir o function resets the position of the directory stream dir to the beginning of the directory. 

RETURN VALUE 

Thereaddiro function returns no value 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3 

SEE ALSO 

opendir(3), readdir(3), closedir(3), seekdir(3), telldir(3), scandir(3) 

11Junel995 


rint 

rint— Rounds to closest integer 

SYNOPSIS 

#include <math.h> 
double rint(double x); 

DESCRIPTION 

The rint o function roundsx to an integer value according to the prevalent rounding mode. The default rounding mode is 
to round to the nearest integer. 

RETURN VALUE 

The rint o function returns the integer value as a floating-point number. 


C0NF0RMST0 
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SEE ALSO 

abs(3), ceil(3), fabs(3), floor(3), labs(3) 


6Junel993 


rquota 

rquota— Implements quotas on remote machines 

SYNOPSIS 

/usr/include/rpcsvc/rquota.x 

DESCRIPTION 

The rquota( ) protocol inquires about quotas on remote machines It is used in conjunction with N FS because N FS itself 
does not implement quotas 

PROGRAMMING 

#include <rpcsvc/rquota.h> 

ThefollowingXDR routines are available in iibrpcsvc: xdr_getquota_arg: 

xdr_getquota_rslt 

xdr_rquota 


SEE ALSO 

quota(l), quotactl(2) 


6 October 1987 


scandir,alphasort 

scandir, alphasort— Scan a directory for matching entries 

SYNOPSIS 

#include <dirent.h> 

int scandir(const char *di r , struct dirent ***namel i st , 
int (*sel ect )(const struct dirent *), 

int (*compar )(const struct dirent **, const struct dirent **)); 
int alphasort(const struct dirent **a, const struct dirent **b); 

DESCRIPTION 

The scandir) ) function scans the di rectory d i r, cal ling select o on each directory entry. Entries for which select)) returns 
non-zero are stored in strings allocated viamaiiocf), sorted using qsorto with the comparison function comparo, and 
collected in array name i st that isallocated viamaiioc().lf select is null, all entries are selected. 

The aiphasorto function can be used as the comparison function for the scandir o function to sort the directory entries into 
alphabetical order. Its parameters are the two directory entries, a and b, to compare 

RETURN VALUE 

The scandir!) function returnsthe number of directory entries selected or -i if an error occurs. 

The aiphasorto function returns an integer less than, equal to, or greater than zero if thefirst argument is considered to be 
respectively less than, equal to, or greater than the second. 








scanf, fssnf, szanf, vs tanf, vsscanf, vfscanf 


ERRORS 

enomem Insufficient memory to complete the operation 

C0NF0RMST0 

BSD 4.3 

EXAMPLE 

/* print files in current directory in reverse order */ 

#include <dirent.h> 
main(){ 

struct dirent “nameli st ; 


n = scandir(".", &n a me I i st , 0 , al phasort ); 


perror("scandir"); 

else 

while(n —) printf("%s\n", namel i st [n]->d_name); 


SEE ALSO 

opendir(3), readdir(3), closedir(3), rewinddir(3), telldir(3), seekdir(3) 


GNU, 11 April 1996 


scant, f scant, sscanf, vscanf, vsscanf, vf scant 

scant, f scant, sscanf, vscanf, vsscanf, vf scant— Input format Conversion 

SYNOPSIS 

#include <stdio.h> 

int scanf( const char ‘format, ...); 

int fscant( FILE ‘stream, const char ‘format, ...); 

int sscanf( const char *str, const char ‘format, ...); 

ffinclude <stdarg.h> 

int vscanf( const char *for mat ,valist ap); 

int vfscant( FILE ‘stream, const char ‘format ,va_list ap); 

DESCRIPTION 

The scant family of functions scans input according to a format as described below. This format may contain conversion 
specifiers; the results from such conversions, if any, are stored through the pointer arguments The scant function reads 
input from the standard input stream stdin, f scant reads input from the stream pointer stream, and sscanf reads its input 
from the character string pointed to by s t r . 

T he vf scant function is analogous to vf printf (3) and reads input from the stream pointer stream using a variable argument 
list of pointers (see stdarg(3)). The vscanf function scans a variable argument list from the standard input and the vsscanf 
function scans it from a string; these are analogous to the vprintf and vsprtntf functions respectively. 

Each successive pointer argument must correspond properly with each successive conversion specifier. All conversions are 
introduced by the % (percent sign) character. The format string may also contain other characters Whitespace (such as 
blanks, tabs, or newlines) in the format string match any amount of whitespace including none, in the input. Everything else 
matches only itself. Scanning stops when an input character does not match such a format character. Scanning also stops 
when an input conversion cannot be made. 
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CONVERSIONS 

Following the% character introducing a conversion, there may be a number of flag characters, as follows: 

* Suppresses assignment. Theconversion that follows occursas usual, but no pointer is used; the result of 
the conversion is simply discarded. 

a Indicates that the conversion will bes, maiioc will be applied to the needed memory space for the string, 
and the pointer to it will be assigned to the char pointer variable, which does not have to be initialized 
before. Thisflag does not exist in AN SI C. 

h Indicates that the conversion will be one of dioux orn and the next pointer is a pointer to a short int 
(rather than ibt). 

1 Indicates either that theconversion will be one of dioux or n and the next pointer isa pointer to a long 
int (rather than int), or that the conversion will be one of efg and the next pointer isa pointer to 
double (rather than float). Specifying two 1 flags is equivalent to the l flag. 
l Indicates that the conversion will be either efg and the next pointer isa pointer to long double or the 
conversion will be dioux and the next pointer isa pointer to long long. (Note that long long is not an 
AN SI C type. Any program using this will not be portable to all architectures), 
q Equivalent to l. Thisflag does not exist in ANSI C. 

In addition to these flags, there may bean optional maximum field width, expressed asa decimal integer, between the% and 
theconversion. If no width is given, a default of infinity is used (with one exception, below); otherwise at most this many 
characters are scanned in processing the conversion. Before conversion begins, most conversions skip whitespace this 
whitespace is not counted against thefield width. 

T he following conversions are available: 

% M atchesa literal %. That is, %% in the format string matches a single input % character. No conversion is 

done, and assignment does not occur. 

d M atches an optionally signed decimal integer; the next pointer must be a pointer to int. 

d Equivalent to id; this exists only for backwards compatibility. 

l M atches an optionally signed integer; the next pointer must be a pointer to int. The integer is read in 

base 16 if it begins with ox or ox, in base 8 if it begins with 0, and in base 10 otherwise. 0 nly 
characters that correspond to the base are used. 

0 M atches an unsigned octal integer; the next pointer must be a pointer to unsigned int. 

u M atches an unsigned decimal integer; the next pointer must be a pointer to unsigned int. 

x M atches an unsigned hexadecimal integer; the next pointer must be a pointer to unsigned int. 

x Equivalent to x. 

f M atchesan optionally signed floating-point number; the next pointer must be a pointer to float, 

e Equivalent to f. 

9 Equivalent to f. 

e Equivalent to f. 

s M atches a sequence of nonwhitespace characters; the next pointer must be a pointer to char, and the 

array must be large enough to accept all the sequence and the terminating NUL character. The input 
string stops at whitespace or at the maximum field width, whichever occurs first, 
c M atches a sequence of width count characters (default 1); the next pointer must be a pointer to char, 

and there must be enough room for all the characters (no terminating nul isadded). The usual skip of 
leading whitespace is suppressed. T0 skip whitespace first, use an explicit space in theformat. 

[ M atchesa nonempty sequence of characters from the specified set of accepted characters; the next 

pointer must be a pointer to char, and there must be enough room for all the characters in the string, 
plus a terminating nul character. The usual skip of leading whitespace issuppressed. The string isto be 
made up of characters in (or not in) a particular set; the set is defined by the characters between the 
open bracket [ character and a close bracket ] character. The set excludes those characters if the first 



seekdir 


character after the open bracket isa circumflex (-). To include a close bracket in the set, make it the 
first character after the open bracket or the circumflex; any other position will end the set. The hyphen 
character (-) is also special; when placed between two other characters, it adds all intervening 
characters to the set. T o include a hyphen, make it the last character before the final close bracket. For 
instance, ne-g-] meanstheset "everything except close bracket, zero through nine, and hyphen." 
The string ends with the appearance of a character not in (or, with a circumflex, in) the set or when 
the field width runs out. 

M atchesa pointer value (as printed by %p in printf (3); the next pointer must be a pointer to void. 

N othing is expected; instead, the number of characters consumed thus far from the input is stored 
through the next pointer, which must be a pointer to int. This is not a conversion, although it can be 
suppressed with the * flag. 


RETURN VALUES 

These functions return the number of input items assigned, which can be fewer than provided for, or even zero, in the event 
of a matching failure. Zero indicates that, while there was input available, no conversions were assigned; typically, this is due 
to an invalid input character, such as an alphabetic character for a %d conversion. The value eof isreturned if an input failure 
occurs before any conversion such as an end-of-file occurs If an error or end-of-file occurs after conversion has begun, the 
number of conversions which were successfully completed is returned. 

SEE ALSO 

strtol(3), strtoul(3), strtod(3), getc(3), printf(3) 

STANDARDS 

The functions f scant, scant, and sscant conform to AN SI C3.159-1989 (AN SI C). 

The q flag isthe BSD 4.4 notation for long long, while n or the usageofL in integer conversions istheGN U notation. 

The Linux version of these functions is based on theGN U ubio library. T ake a look at the into documentation of GN U 
libc (glibc-1.08) for a more concise description. 

BUGS 

All functions are fully AN SI C3.159-1989-conformant, but provide the additional flags q and a as well as an additional 
behavior of the l and i flags T he latter may be considered to be a bug, as it changes the behavior of flags defined in AN SI 
C 3.159-1989. 

Some combinations of flags defined by ANSI C are not making sense in ANSI C (for example %Ld). Whiletheymayhavea 
well-defined behavior on Linux, this need not to be so on other architectures. Therefore, it usually is better to use flags that 
are not defined by AN SI C at all, that is useq instead of l in combination with diouxx conversionsor if. 

The usage ofq isnot the same ason BSD 4.4, as it may be used in float conversions equivalently to l. 

Linux man page 1 N ovember 1995 


seekdir 

seekdir— Sets the position of the next readdiro call in the directory stream. 

SYNOPSIS 

#include <dirent.h> 

void seekdir (DIR *di r, of f_t offset); 

DESCRIPTION 

The seekdiro function sets the location in the directory stream from which the next readdiro call will start, seekdir) > 
should be used with an offset returned by teiidiro. 
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RETURN VALUE 

Theseekdiro function returns no value 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

lseek(2), opendir(3), readdir(3), closedir(3), rewinddir(3), telldir(3), scandir(3) 


31 March 1993 


setbuf,setbuffer,setlinebuf,setvbuf 

setbuf, setbuffer, setlinebuf, setvbuf— Stream buffering operations 

SYNOPSIS 

#include <stdio.h> 

int setbuff FILE ‘stream, char *buf); 

int setbuffer! FILE ‘stream, char *buf , size_tsize); 

int setlinebuf! FILE ‘stream); 

int setvbuf! FILE ‘stream, char *buf, i ntmode , size_t size); 

DESCRIPTION 

Thethree types of buffering available are unbuffered, block buffered, and line buffered. When an output stream is unbuf¬ 
fered, information appears on the destination file or terminal as soon as written; when it is block buffered, many characters 
are saved up and written asa block; when it is line buffered, characters are saved up until a newline isoutput or input is read 
from any stream attached to a terminal device (typically stdin). Thefunction ffiush(3) may be used to force the block out 
early. (See f ciose(3).) Normally all files are block buffered. When thefirst I/O operation occurs on a file maiioc(3) is called, 
and a buffer is obtained. If a stream refers to a terminal (asstdout normally does), it is line buffered. The standard error 
stream stderr isalwaysunbuffered. 

The setvbuf function may be used at any time on any open stream to change its buffer. The mode parameter must be one of 
thefollowing three macros: 

_ionbf Unbuffered 

_iolbf Line buffered 

_iofbf Fully buffered 

Except for unbuffered files, the but argument should point to a buffer at least size bytes long; this buffer will be used instead 
of the current buffer. If the argument buf is null, only the mode is affected; a new buffer will be allocated on the next read or 
write operation. The setvbuf function may be used at anytime, but can only change the mode of a stream when it is not 
"active"; that Is, before any I/O, or immediately after a call to ffiush. 

Theother three calls are, in effect, simply aliases for calls to setvbuf. The setbuf function isexactly equivalent to the call: 

setvbuf(stream, buf, buf ?_I0FBF :_I0NBF, BUFSIZ); 

The setbuffer function is the same, except that the size of the buffer is up to the caller, rather than being determined by the 
default bufsiz. The setlinebuf function isexactly equivalent to the call: 

earn, (char *)NULL,_IOLBF, 0); 


setvbuf(s t r < 




setenv 


SEE ALSO 

fopen(3), fclose(3), fread(3), malloc(3), puts(3), printf(3) 

STANDARDS 

The setbuf and setvbuf functionsconformtoANSI C3.159-1989 (ANSI C). 

BUGS 

Thesetbuffer and setiinebuf functions are not portable to versions of BSD before 4.2BSD, and may not be available under 
Linux. On 4.2BSD and 4.3BSD systems, setbuf alwaysusesasuboptimal buffer size and should be avoided. You must make 
sure that both buf and the space it points to still exist by the time stream is closed, which also happens at program termina¬ 
tion. For example, thefollowing is illegal: 

#include <stdio.h> 
int main() 

{ 

char buf[BUFSIZ]; 
setbuf(stdin, buf ); 
printf("Hello, world!\n"); 
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setenv 

setenv- Changes or adds an environment variable 

SYNOPSIS 

ffinclude <stdlib.h> 

int setenv(const char ‘name, const char ‘value,int overwrite); 
void unsetenv(const char ‘name); 

DESCRIPTION 

The setenv () function adds the vari able name to the en vi ronment with the value value, if n a me does not already exist. I f n a me 
does exist in the environment, then its value is changed to value if overwrite is non-zero; if overwrite is zero, then the value 
of name is not changed. 

The unsetenvo function deletes the variable name from the environment. 

RETURN VALUE 

The setenv) ) function returns zero on success, or -i if there was insufficient space in the environment. 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

getenv(3), putenv(3) 


BSD, 4 April 1993 
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setjmp 

setjmp— Saves stack context for nonlocal goto 

SYNOPSIS 

#include <setjmp.h> 
int setjmp!jmp_buf env ); 

DESCRIPTION 

setjmp and iongjmp(3) are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program, 
setjmp () saves the stack context/environment in env for later use by longjmpo. The stack context will beinvalidated if the 
function which called setjmpo returns 

RETURN VALUE 

It returnsthe value 0 if returning directly and non-zero when returning from longjmpt > using the saved context. 

C0NF0RMST0 

POSIX 

NOTES 

POSIX does not specify if the signal context will be saved or not. If you want to save signal masks usestgsetjmp(3). setjmpo 
makes programs hard to understand and maintain. If possible an alternative should be used. 

SEE ALSO 

longjmp(3), sigsetjmp(2), siglongjmp(2) 

25 November 1994 


setlocale 

setiocaie— Sets the current locale 

SYNOPSIS 

#include <locale.h> 

char *setlocale(int category, const char * locale); 

DESCRIPTION 

The setiocaiei ) function is used to set or query the program's current locale If 1 ocai e isC or PO SIX, the current locale is 
set to the portable locale. 

If 1 oca 1 e is 11 ", the locale isset to the default locale that is selected from the environment variableLANG. 

0 n startup of the main program, the portable locale isselected as default. 

Theargumentcategory determines which functions are influenced by the new locale: 
lc_all For all of the locale 

LC_COLLATE For the functions strcoll( ) and strxfrm(). 

lc_ctype For the character classification and conversion routines 

LC_MONETARY For localeconv(). 

lc_numeric For the decimal character. 

lc_time For strf time (). null if the request can not be honored. This string may be 

allocated in static storage. 




sigemptyset, sigfillsst, s'gaddsst, a'gddset, s'gismember 


A program may be made portable to all locales by calling setiocaie(LC_ALL, .) after program initialization, by using the 

values returned from aiocaieconvo call for locale-dependent information and by using strcoiio or strxfrmo to compare 
strings. 

C0NF0RMST0 

ANSI C.POSIX.1 

Linux supports the portable locales C and POSIX and also theEuropean Latin-1 and Russian locales. 

The printf () family of functions may or may not honor the current locale 

SEE ALSO 

locale(l), localedef(l), strcoll(3), isalpha(3), localeconv(3), strftime(3), locale(7) 

GNU, 18 April 1993 


siginterrupt 

siginterrupt— Allows signals to interrupt system calls 

SYNOPSIS 

#include <signal.h> 

int siginterrupt(int sig.int flag); 

DESCRIPTION 

The siginterrupt) ) function changes the restart behavior when asystem call is interrupted by thesignal sig.lf the flag 
argument is false ( 0 ), then systems calls will be restarted if interrupted by the specified signal sig. This isthe default behavior 
in Linux. However, when anew signal handler isspecified with thesignai(2) function, the system call is interrupted by 
default. 

If the flag argument istrue ( 1 ) and no data has been transferred, then a system call interrupted by the signal sig will return 
-1 and the global variableerr no will besetto eintr. 

If the flag argument istrue ( 1 ) and data transfer has started, then thesystem call will be interrupted and will return the 
actual amount of data transferred. 

RETURN VALUE 

The siginterrupt)) function returnso on success, or -1 if the signal number sig isinvalid. 

ERRORS 

einval Thespecified signal number isinvalid. 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

signal(2) 

13 April 1993 

sigemptyset,sigfillset,sigaddset, sigdelset, sigismember 

sigemptyset, sigfillset, sigaddset, sigdelset, sigismember— PO SIX signal Set operations 
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SYNOPSIS 

#include <signal.h> 

int sigemptyset(sigset_t *set); 

int sigfillset(sigset_t *set); 

int sigaddset(sigset_t *set,int signum); 

int sigdelset(sigset_t *set,int signum); 

int sigismember(const sigset_t *set,int signum); 

DESCRIPTION 

The sigsetops(3) functionsallow the manipulation of PO SIX signal sets 

sigemptyset initializes the signal set given by set to empty, with all g gnals excluded from theset. 

sigfiiiset initializesset to full, including all signals 

sigaddset and sigdeiset add and delete, respectively, signal signum from set. 

sigismember tests whether s i g n u m isa member Of set. 

RETURN VALUES 

sigemptyset, sigfuiiset, sigaddset, and sigdeiset return 0 on success and -i on error, 
sigismember returns i if signum is a member of set, 0 if signum is not a member, and -i on error. 

ERRORS 

einval s i g is not a valid signal. 


C0NF0RMST0 

POSIX 

SEE ALSO 

sigaction(2), sigpending(2), sigprocmask(2), sigsuspend(2) 


Linux 1.0, 24 September 1994 


sin 

sin— Sinefunction 

SYNOPSIS 

#include <math.h> 
double sin(double x); 

DESCRIPTION 

Thesmo function returns the sine of x, where x isgiven in radians 

RETURN VALUE 

Thesino function returns a value between -i and i. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 




SEE ALSO 

acos(3), asin(3), atan(3), atan2(3),cos(3),tan(3) 


8Junel993 


sinh 

sinh— H yperbolic sine function 

SYNOPSIS 

#include <math.h> 
double sinh(double x); 

DESCRIPTION 

The sinh () function returns the hyperbolic sineof x, which is defined mathematically as [exp(x)-exp(-x)] / 2. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

acosh(3), asinh(3), atanh(3), cosh(3), tanh(3) 

13Junel993 


sleep 

sleep- Sleeps for the specified number of seconds 

SYNOPSIS 

#include <unistd.h> 

unsigned int sleep(unsigned int seconds); 

DESCRIPTION 

sieepo makes the current process sleep until seconds seconds have elapsed or a signal arrives that is not ignored. 

RETURN VALUE 

T he return value is zero if the requested time has elapsed, or the number of seconds left to sleep. 

C0NF0RMST0 

POSIX.1 

BUGS 

sleep!) may be implemented using sigalrm; mixing calls to alarm!) and sleep o is a bad idea. 

Using longjmpo from a signal handler or modifying the handling of sigalrm while sleeping will cause undefined results 

SEE ALSO 

signal(2), alarm(2) 


GNU, 7April 1993 
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snprintf,vsnprintf 

snprintf, vsnprintf— Formatted output conversion 

SYNOPSIS 

#include <stdio.h> 

int snprintf ( char *str, size_t n, 

#include <stdarg.h> 

int vsnprintf ( char *$tr, size_t n, 
const char ‘format, va_list ap ); 

DESCRIPTION 

snprintf writes output to the string s t r , under control of thef or mat string that specifies how subsequent arguments are 
converted for output. It issimilarto sprtntf(3), except that n specifies the maximum number of characters to produce. 

The trailing null character is counted towards this limit, so you should allocate at least n characters for the string s t r . 
vsnprintf is the equivalent of snprintf with the variable argument list specified directly as for vprintf. 

RETURN VALUE 

The return value is the number of characters stored, not including the terminating null. If this value equals n, then there was 
not enough space in str for all the output. You should try again with a bigger output string. 

EXAMPLE 

H ere is a sample program that dynamically enlarges its output buffer: 

/* Construct a message describing the value of a 
variable whose name is NAME and whose value is 
VALUE. */ 

makejnessage (char ‘name, char ‘value) 

/* Guess we need no more than 100 chars of space. */ 
int size = 100; 

char ‘buffer = (char *) xmalloc (size); 
while (1) 

/* Try to print in the allocated space. */ 
int nchars = snprintf (buffer, size, 

/* If that worked, return the string. */ 
if (nchars < size) 
return buffer; 

/* Else try again with twice as much space. */ 
size *= 2; 

buffer = (char *) xrealloc (size, buffer); 


C0NF0RMST0 

TheseareGNU extensions 




stdarg 


SEE ALSO 

printf(3), sprintf(3), vsprintf(3), stdarg(3) 


GNU, 16 September 1995 


sqrt 

sqrt — Square root function 

SYNOPSIS 

#include <math.h> 
double sqrt(double x); 

DESCRIPTION 

T he sqrt o function returns the non-negative square root ofx. Itfails and sets er r no tOEDOM, if x is negative. 

ERRORS 

edom x is negative. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

hypot(3) 

21Junel993 


stdarg 

stdarg— Variable argument lists 

SYNOPSIS 

#include <stdarg.h> 
void va_start( va_list ap, last); 
type va_arg( va_list ap, type); 
void va_end( va_list ap); 

DESCRIPTION 

A function may be called with a varying number of arguments of varying types. The include file stdarg. h declares a type 
va_iist and defines three macros for stepping through a list of arguments whose number and types are not known to the 
called function. 

The called function must declare an object of type va_itst that is used by the macros va_start, va_arg, and va_end. 
Theva_start macro initializesap for subsequent use by va_arg and va_end, and must be called first. 

The parameter last is the name of the last parameter before the variable argument list; that is, the last parameter of which 
the calling function knows the type. 

Because the address of this parameter is used in theva_start macro, it should not be declared as a register variable, a 
function, or an array type 
Theva_start macro returns no value. 



Part III: L ibrary Functions 


Theva_arg macro expands to an expression that has the type and value of the next argument in the call. T he parameter a p is 
the va_iist ap initialized by va_start. Each call to va_arg modifies a p so that the next call returnsthe next argument. The 
parameter type is a type name specified so that the type of a pointer to an object that has the specified type can be obtained 
simply by adding a * to type. 

If there is no next argument, or if type is not compatible with the type of the actual next argument (as promoted according 
to the default argument promotions), random errors will occur. 

Thefirst useof theva_arg macro after that of the va_start macro returns the argument after last. Successive invocations 
return the values of the remaining arguments 

Theva_end macro handles a normal return from the function whose variable argument list was initialized by vajstart. 
Theva_end macro returns no value 

EXAMPLE 

The function foo takes a string of format characters and prints out the argument associated with each format character based 
on the type 

void foo(char *fmt, ...) 

I 

va_list ap; 
ini d; 


va_start(ap, fmt); 
while (*fmt) 

switch(*fmt++) { 

case 's': /* string */ 

s = va_arg(ap, char *); 
printf("string %s\n", s); 

case 1 d': /* int */ 

d = va_arg(ap, int); 
printf("int %d\n", d); 


c = va_arg(ap, char); 
printf("char %c\n", c); 


va_end(ap); 


STANDARDS 

Theva_start, va_arg, and va_end macros conform to AN SI C 3.159-1989 (ANSI C). 

COMPATIBILITY 

These macros are not compatible with the historic macros they replace A backwards-compatible version can be found in the 
include file varargs.h. 

BUGS 

U nlike the varargs macros, the stdarg macros do not permit programmers to code a function with no fixed arguments This 
problem generates work mainly when converting varargs code to stdarg code but it also creates difficulties for variadic 
functions that wish to pass all of their argumentson to a function that takesa va_iist argument, such as vf printf (3). 

BSD man page, 29 N ovember 1993 
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stdio 

stdio— Standard input/output library functions 

SYNOPSIS 

#include <stdio.h> 

FILE *stdin; 

FILE ‘stdout; 

FILE *stderr; 

DESCRIPTION 

The standard I/O library provides a simple and efficient buffered stream I/O interface. Input and output is mapped into 
logical data streams and the physical I/O characteristics are concealed. The functions and macros are listed in thissection; 
more information isavailablefrom theindividual man pages. 

A stream is associated with an external file (which may be a physical device) by opening a file, which may involve creating a 
new file Creating an existing file causesits former contents to bediscarded. If a file can support positioning requests (such as 
a disk file asopposed to a terminal), then a file position indicator associated with the stream is positioned at the start of the 
file (byte zero), unless the file is opened with append mode. If append mode is used, the position indicator will be placed the 
end-of-file. The position indicator is maintained by subsequent reads, writes, and positioning requests. All input occurs as if 
the characters were read by successive calls to thefgetc(3) function; all output takes place as if all characters were read by 
successive calls to thetputc(3) function. 

A file is disassociated from a stream by closing the file. 0 utput streams are flushed (any unwritten buffer contents are 
transferred to the host environment) before the stream is disassociated from the file The value of a pointer to a file object is 
indeterminate after a file isdosed (garbage). 

A file may be subsequently reopened, by the same or another program execution, and its contents reclaimed or modified (if it 
can be repositioned at the start). If the main function returns to its original caller, ortheexit(3) function is called, all open 
files are closed (hence all output streams are flushed) before program termination. Other methods of program termination, 
such asabort(3) do not bother about closing files properly. 

At program startup, three text streams are predefined and need not be opened explicitly: standard input (for reading 
conventional input), standard output (for writing conventional input), and standard error (for writing diagnostic output). 
These streams are abbreviated stain, stdout, and stderr. W hen opened, the standard error stream is not fully buffered; the 
standard input and output streams are fully buffered if and only if the streams do not to refer to an interactive device. 

Output streams that refer to terminal devices are always line buffered by default; pending output to such streams is written 
automatically whenever an input stream that refers to a terminal de/ice is read. In cases where a large amount of computation 
is done after printing part of a line on an output terminal, it is necessary to ffiush(3) the standard output before going off 
and computing so that the output will appear. 

The stdio library is a part of the library iibc and routines are automatically loaded as needed by the compilers cc(l) and 
pc( 1) . The synopsis sections of the following manual pages indicate which include files are to be used, what the compiler 
declaration for the function looks like, and which external variables are of interest. 

Thefollowing are defined as macros; these names may not be reused without first removing their current definitions with 

#undef: BUFSIZ, EOF, FILENAME_MAX, FOPENJIAX, L_cuserid, L_ctermid, LJunpnam, NULL, SEEK_END, SEEK_SET, SEE_CUR, TMP_MAX, 
clearerr, feof, terror, fileno, fropen, fwopen, getc, getchar, putc, putchar, stderr, stdin, stdout. Function Versions Of the 
macro functions feof, terror, clearerr, fileno, getc, getchar, putc, and putchar exist and Will beUSed if the macros 
definitionsareexplicitly removed. 

SEE ALSO 

open(2), close(2), read(2), write(2) 
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BUGS 

The standard buffered functionsdo not interact well with certain other library and system functions, especially vtork and 
abort. This may not be the case under Linux. 

STANDARDS 

Thestdio library conforms to AN SI C3.159-1989 (ANSI C). 

LIST OF FUNCTIONS 


Function 


Desription 


fdopen 

feof 

terror 

fflush 

fgetc 

fgetline 

fgetpos 

fgets 

fileno 

fopen 

fprintf 

fpurge 

freopen 

fropen 

fseek 

fsetpos 

ftell 


getchar 

mktemp 


C heck and reset stream status 
C lose a stream 
Stream open functions 
C heck and reset stream status 
C heck and reset stream status 
Flush a stream 

Get next character or word from input stream 

Getalinefrom a stream 

Reposition a stream 

Getalinefrom a stream 

C heck and reset stream status 

Stream open functions 

Formatted output conversion 

Flush a stream 

0 utput a character or word to a stream 

Output a line to a stream 

Binary stream input/output 

Stream open functions 

0 pen a stream 

I nput format conversion 

Reposition a stream 

Reposition a stream 

Reposition a stream 

Binary stream input/output 

Get next character or word from input stream 

Get next character or word from input stream 

Getalinefrom a stream 

Get next character or word from input stream 

M ake temporary filename (unique) 

System error messages 
Formatted output conversion 
0 utput a character or word to a stream 
0 utput a character or word to a stream 
Output a line to astream 
0 utput a character or word to a stream 




ipcpy p7 

remove 

scant 
setbuf 
setbuffer 
setlinebuf 
setvbuf 

tempnam 
tmpfile 
tmpnam 
ungetc 

vfscanf 

vsscanf 


stpcpy 

stpcpy— Copies a string returning a pointer to its end 

SYNOPSIS 

#include <string.h> 

char *stpcpy(char *dest , const char *src); 

DESCRIPTION 

The stpcpy o function copiesthe string pointed to by src (including the terminating \o character) to the array pointed to by 
dest. The strings may not overlap, and the destination string des t must be large enough to receive the copy. 

RETURN VALUE 

stpcpy o returnsa pointer to the end of the string dest (that is, theaddressof theterminating null character) rather than the 
beginning. 

EXAMPLE 

For example, this program uses stpcpy to concatenate too and bar to produce foobar, which it then prints: 

((include <string.h> 


Remove directory entry 
Reposition a stream 
I nput format conversion 
Stream buffering operations 
Stream buffering operations 
Stream buffering operations 
Stream buffering operations 
Formatted output conversion 
I nput format conversion 
System error messages 
System error messages 
System error messages 
Temporary file routines 
Temporary file routines 
Temporary file routines 
U n-get character from input stream 
Formatted output conversion 
I nput format conversion 
Formatted output conversion 
I nput format conversion 
Formatted output conversion 
I nput format conversion 

BSD man page, 29 N ovember 1993 
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char *to = buffer; 
to = stpcpy (to, "foo") 
to = stpcpy (to, "bar") 
printf ("%s\n", buffer) 


C0NF0RMST0 

Thisfunction is not part of the AN SI or POSIX standards, and is not customary on UN IX systems, but isnotaGN U 
invention either. Perhaps it comes from M S-DOS. 

SEE ALSO 

strcpy(3), bcopy(3), memccpy(3), memcpy(3), memmove(3) 

GN U, 3 September 1995 


strcasecmp,strncasecmp 

strcasecmp, strncasecmp— Compare two strings, ignoring case 

SYNOPSIS 

#include <string.h> 

int strcasecmp(const char *s1, const char *s2); 

int strncasecmp(const char *sl, const char *s2, size_t n); 


DESCRIPTION 

The strcasecmpo function comparesthetwo strings s 1 and s 2 , ignoring the case of the characters. Itreturnsan integer less 
than, equal to, or greater than zero if s 1 isfound, respectively, to be less than, to match, or be greater than s 2 . 

The strncasecmp( ) function is similar, except it only compares thefirst n characters of s 1 . 

RETURN VALUE 

The strcasecmpo and strncasecmp! ) functions return an integer less than, equal to, or greater than zero if si (or thefirst n 
bytes thereof) isfound, respectively, to be less than, to match, or be greater than s 2 . 

C0NF0RMST0 

BSD 4.3 


SEE ALSO 

bcmp(3), memcmp(3), strcmp(3), strcoll(3), strncmp(3) 


11 April 1993 


strcat,strncat 

strcat, strncat— Concatenate two strings 

SYNOPSIS 

#include <string.h> 

char *strcat(char *dest , const char *src); 

char *strncat(char *dest , const char *src, size_t n); 




strcmp, strncmp 


DESCRIPTION 

Thestrcato function appendsthesrc string to the dest string, overwriting the \a character at the end of dest , and then 
adds a terminating \e character. Thestringsmay not overlap, and thedest string must haveenough space for the result. 
T he stmeat () function is similar, except that only thefirst n characters of s r c are appended to dest . 

RETURN VALUE 

Thestrcato and strncato functions return a pointer to the resulting string des t. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 


SEE ALSO 

bcopy(3), memccpy(3), memcpy(3), strcpy(3), strncpy(3) 


GNU, 11 April 1993 


strehr, strrehr 

strehr, strrehr— Locate character in string 

SYNOPSIS 

#include <string.h> 

char *strchr(const char *s,int c); 

char *strrchr(const char *s,int c); 

DESCRIPTION 

Thestrchro function returns a pointer to thefirst occurrence of the character c in the strings. 

The strrchr() function returns a pointer to the last occurrence of the character c in the strings. 

RETURN VALUE 

Thestrchro and strrehr o functions return a pointer to the matched character or null if the character is not found. 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

index(3), memchr(3), rindex(3), strpbrk(3), strsep(3), strspn(3), strstr(3), strtok(3) 

12 April 1993 


strcmp,strncmp 

strcmp, strncmp—Compare two strings 

SYNOPSIS 


#include <string.h> 

int strcmp(const char *sl, ( 

int strncmp(const char *sl, 
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DESCRIPTION 

The strcmp( ) function compares the two stringssi and s 2 . It returns an integer less than, equal to, or greater than zero if si 
is found, respectively, to be less than, to match, or be greater than s 2 . 

The strncmpi ) function issimilar, except it only compares the firstn characters of si. 

RETURN VALUE 

The strcmp( ) and strncmpo functions return an integer less than, equal to, or greater than zero if si (or thefirst n bytes 
thereof) isfound, respectively, to be less than, to match, or be greater than s 2 . 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

bcmp(3), memcmp{3), strcasecmp(3), strncasecmp(3), strcoll(3) 

11 April 1993 


strcoll 

st rcoii— Compares two strings using the current locale 

SYNOPSIS 

#include <string.h> 

int strcoll(const char *sl, const char *s2); 

DESCRIPTION 

Thestrcoiio function compares the two strings s 1 and s 2 . It returns an integer less than, equal to, or greater than zero if si 
isfound, respectively, to be less than, to match, or be greater than s 2 . The comparison is based on strings interpreted as 
appropriate for the program's current localefor category lc_collate. (See setiocaie(3)). 

RETURN VALUE 

Thestrcoiio function rdturnsan integer less than, equal to, or greater than zero if si isfound, respectively, to be less than, 
to match, or be greater than s 2 , when both are interpreted as appropriate for the current locale 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

NOTES 

The Linux C Library currently hasn't implemented the complete PO SIX-collating. 

In thePOSIX orC locales, strcoiio is equivalent to strcmpo. 

SEE ALSO 

bcmp(3), memcmp(3), strcasecmp(3), strcmp(3), strxfrm(3), setlocale(3) 

GNU, 12 April 1993 


strcpy,strncpy 

strcpy, strncpy— Copy a string 



irdup 


SYNOPSIS 

#include <string.h> 

char *strcpy(char *dest , const char *src); 

char ‘strncpy(char *dest , const char *src, size_t n); 

DESCRIPTION 

Thestrcpyo function copiesthe string pointed to be s r c (including the terminating \o character) to the array pointed to by 
dest. The strings may not overlap, and the destination string des t must be large enough to receive the copy. 

The strncpy) ) function is similar, except that not more than n bytes of s r c are copied. Thus, if there is no null byte among 
the first n bytes of s re, the result will not be null-terminated. 

In the case where the length of sre islessthan that of n, the remainder ofdest will be padded with nulls. 

RETURN VALUE 

Thestrcpyo andstrncpyo functions return a pointer to the destination string dest. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

bcopy(3), memccpy(3), memcpy(3), memmove(3) 

GNU, 11 April 1993 


strdup 

strdup — D uplicatesa string 

SYNOPSIS 

#include <string.h> 

char *strdup(const char *s); 

DESCRIPTION 

T he strdup) ) function returns a pointer to a new string that is a duplicate of the string s. M emory for the new string is 
obtained with maiioc(3), and can be freed with t ree(3). 

RETURN VALUE 

T he strdup( ) function returns a pointer to the duplicated string, or null if insufficient memory was available. 

ERRORS 

enomem Insufficient memory available to allocate duplicate string 

C0NF0RMST0 

SVID 3, BSD 4.3 

SEE ALSO 

calloc(3), malloc(3), realloc(3), free(3) 


GNU, 12 April 1993 
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strerror 

strerror— Returns string describing error code 

SYNOPSIS 

#include <string.h> 

DESCRIPTION 

The strerror( ) function returns a string describing the error code passed in the argument er mum. The string can only be 
used until the next call to strerror!). 

RETURN VALUE 

The strerror!) function returns the appropriate description string,or an unknown error message if the error code is 
unknown. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

errno(3), perror(3), strsignal(3) 

GNU, 13 April 1993 


strfry 

strtry— Randomizesa string 

SYNOPSIS 

#include <string.h> 
char *strfry(char *st ring); 

DESCRIPTION 

The strtryo function randomizes the contents of stri ng by using rand(3) to randomly swap characters in the string. The 
result is an anagram of s t r i ng. 

RETURN VALUE 

The strtryo function returns a pointer to the randomized string. 

C0NF0RMST0 

The strfryo function is unique to the Linux C Library andGNU C Library. 

SEE ALSO 

memfrob(3) 

GNU, 12 April 1993 


strftime 


strftime— Formats date and time 



irftime 


SYNOPSIS 

#include <time.h> 

size t strftime(char *s, size_t max, const char ‘format, 
const struct tm *t m); 

DESCRIPTION 

The strftime( ) function formats the broken-down timet m according to the form at specification format and places the result 
in the character array s of size ma x. 

Ordinary characters placed in theformat string are copied to s without conversion. Conversion specifiers are introduced by a 
% character, and are replaced in s as follows: 

%a The abbreviated weekday nameaccordingto thecurrent locale 

%a Thefull weekday nameaccordingto thecurrent locale 

%b T he abbrevi ated month name according to the current locale 

%b Thefull month nameaccordingto thecurrent locale 

%c T he preferred date and time representation for the current locale 

%d The day of the month as a decimal number (range 01 to 31) 

%h T he hour as a decimal number using a 24-hour clock (range 00 to 23) 

%i T he hour as a decimal number using a 12-hour clock (range 01 to 12) 

%j The day of the year as a decimal number (range 001 to 366) 

%m The month as a decimal number (range 01 to 12) 

%m Theminuteasadecimal number 

%p E ither a.m. or p.m. according to the given time value, or the corresponding strings for the current 

locale 

%s The second as a decimal number 

%u The week number of the current year as a decimal number, starting with the first Sunday as the first 

day of the first week 

%w The week number of thecurrent year as a decimal number, starting with the first M onday as the first 

day of the first week 

%w The day of the week as a decimal, Sunday being 0 

%x The preferred date representation for the current locale without the time 

%x The preferred time representation for the current locale without the date 

%y Theyear asa decimal number without a century (range 00 to 99) 

%y Theyear asa decimal number including the century 

%z The time zone or name or abbreviation 

%% A literal % character 

The broken-down time structure tm is defined in <time.h> asfollows 
struct tm 
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T he members of the tm structure are 

tm_sec The number of seconds after the minute, normally in the range 0 to 59, but can be up to 

61 to allow for leap seconds 

tmjnin The number of minutes after the hour, in therangeOto 59. 

tm_hour The number of hours past midnight, in therangeOto 23. 

tm_mday T he day of the month, in the range 1 to 31. 

tmjnon The number of monthssincejanuary, in the range 0 to 11. 

tm_year The number of years since 1900. 

tm_wday The number of days since Sunday, in therangeO to 6. 

tm_yday T he number of days since J anuary 1, in the range 0 to 365. 

tm_isdst A flag that indicates whether daylight saving time is in effect at the time described. The 

value is positive if daylight saving time is in effect, zero if it is not, and negative if the 
information is not available 

RETURN VALUE 

The strftime( ) function returns the number of characters placed in the arrays, not including the terminating null character. 
If the value equals max, it meansthat the array was too small. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

date(l), time(2), ctime(3), setlocale(3), sprintf(3) 

NOTES 

Thefunction supports only those locales specified in iocaie(7) 

GNU, 2July 1993 

strcasecmp, strcat, strchr, strcmp, strcoll, strcpy, strcspn, 
strdup, strf ry, strlen, strncat, strncmp, strncpy, strncasecmp, 
strpbrk, strrchr, strsep, strspn, strstr, strtok, strxf rm, 
index,rindex 

strcasecmp, strcat, strchr, strcmp, strcoll, strcpy, strcspn, strdup, strfry, strlen, strncat, strncmp, strncpy, strncasecmp, 
strpbrk, strrchr, strsep, strspn, strstr, strtok, strxf rm, index, rindex— String operations 

SYNOPSIS 

#include <string.h> 

int strcasecmpjconst char *sl, const char *s2); 
char *strcat(char *dest, const char *src); 
char *strchr(const char *s,int c); 
int strcmp(const char *sl, const char *s2); 
int strcoll(const char *sl, const char *s2); 
char *strcpy(char *dest , const char *src); 
size_t strcspn(const char *s , const char ‘reject); 
char *strdup(const char *s); 






strpbrk 


char *strfry(char *st ring); 
size_t strlen(const char *s); 

char *strncat(char *dest , const char *src, size_t n); 
int strncmp(const char *sl, const char *s2, size_t n); 
char *strncpy(char *dest , const char *src, size_t n); 
int strncasecmp(const char *sl, const char *s2, size_t n); 
char *strpbrk(const char *s, const char ‘accept); 
char *strrchr(const char *s,int c); 
char *strsep(char “stringp, const char *d eIim); 
size_t strspn(const char *s, const char ‘accept); 

char *strtok(char *s, const char ‘del i m); 
size_t strxfrm(char *dest , const char *src, size_t n); 
char *i ndex (const chart's,i nt c); 
char *rindex(const char *s,int c); 

DESCRIPTION 

The string functions perform string operationson NULL-terminated strings. Seethe individual man pages for descriptions of 
each function. 

SEE ALSO 

index(3), rindex(3), strcasecmp(3), strcat(3), strchr(3), strcmp(3), strcoll(3), strcpy(3), strcspn(3), strdup(3), strfry(3), 
strlen(3), strncat(3), strncmp(3), strncpy(3), strncasecmp(3), strpbrk(3), strrchr(3), strsep(3), strspn(3), strstr(3), 
strtok(3), strxfrm(3) 

9 April 1993 


strlen 

strien— Calculates the length of a string 

SYNOPSIS 

#include <string.h> 

DESCRIPTION 

The strien( ) function calculates the length of the strings, not including theterminating \0 character. 

RETURN VALUE 

The strien( ) function returns thenumber of characters ins. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

string(3) 

12 April 1993 


strpbrk 

strpbrk— Searches a string for any of a set of characters 
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SYNOPSIS 

ffinclude <string.h> 

char *strpbrk(const char *s, const char ‘accept); 

DESCRIPTION 

The strpbrk () function locates the first occurrence in the strings of any of the characters in thestringaccept. 

RETURN VALUE 

T he strpbrk) ) function returns a pointer to the character in % that matches one of the characters in accept. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

index(3), memchr(3), rindex(3), strchr(3), strsep(3), strspn(3), strstr(3), strtok(3) 

12 April 1993 


strptime 

strptime- Converts a string representation of time to a time tm structure 

SYNOPSIS 

#include <time.h> 

char *strptime(char ‘but, const char ‘format, const struct tm *tm); 

DESCRIPTION 

strptime () isthe complementary function to strftimeo and converts the character string pointed to by but to a time value 
which isstored in thetm structure pointed to bytm, using the format specified byformat .format isa character string that 
consists of field descriptors and text characters, reminiscent of scant(3). Each field descriptor consists of a % character 
followed by another character that specifiesthe replacement for the field descriptor. All other characters are copied from 
f o r ma t into the result. T he following field descriptors are supported: 

%% Same as %. 

%a, %a D ay of week, using locale's weekday names; either the abbreviated or full name may be 

specified. 

%b, %b, %h M onth, using locale's month names; either the abbreviated or full name may be 

specified. 

%c D ate and time as%x, %x. 

%c D ate and time, in locale's long-format date and time representation. 

%d, %e D ay of month (1-31; leading zeroes are permitted but not required). 

%d Dateas%m/%d/%y. 

%h, %k H our (0-23; leading zeroes are permitted but not required). 

%i, %i Hour (0-12; leading zeroes are permitted but not required). 

%j Day number of year (001-366). 

%m M onth number (1-12; leading zeroes are permitted but not required). 

%m M inute (0-59; leading zeroes are permitted but not required). 

%p Locale's equivalent of a.m. orp.m. 

%r Timeas%i:%M:%s %p. 




%r Timeas%H:%M. 

%s Seconds(0-61; leading zeroes are permitted but not required; extra second allowed for 

leap years). 

%t Timeas%H:%M:%s. 

%w Weekday number (0-6) with Sunday as the first day of the week. 

%x Date, using I ocale's date format. 

%x Time, using locale's time format. 

%y Year within century (0-99; leading zeroes are permitted but not required. 

U nfortunately, this makes the assumption that we are stuck in the 20th century, as 
1900 is automatically added onto this number for the tm year field.) 

%y Year, including century (for example, 1988). 

Case is ignored when matching items such as month or weekday name. 

The broken-down time structure tm isdefined in <ttme.h> asfollows 


int tm_sec; /* seconds */ 

int tmjnin; /* minutes */ 

int tmjnday; /* day of the month */ 

int tmjnon; /* month */ 

int tm_year; /* yean */ 

int tm_wday; /* day of the week */ 

int tm_yday; /* day in the year */ 

int tm_isdst; /* daylight saving time */ 


RETURN VALUE 

The strptime( ) function returns a pointer to the character following the last character in the string pointed to by buf. 

SEE ALSO 

strftime(3), time(2), setlocale(3), scant(3) 

BUGS 

T he return values point to static data, whose contents are overwritten by each call. 

NOTES 

Thisfunction is only available in libraries newer than version 4.6.5. 

Thefunction supports only those locales specified in iocaie(7). 

GNU, 26 September 1994 


strsep 

strsep— Extracts token from string 

SYNOPSIS 

#include <string.h> 

char *strsep(char **stringp, const char *delim); 
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DESCRIPTION 

Thestrsepo function returns the next token from thestring st r i ngp which is delimited by del i m. The token is terminated 
with a \o character and st ri ngp is updated to point past the token. 

RETURN VALUE 

Thestrsepo function returns a pointer to the token, or null if deiim is not found in stri ngp. 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

index(3), memchr(3), rindex(3), strchr(3), strpbrk(3), strspn(3), strstr(3), strtok(3) 

GNU, 12 April 1993 


strsignal 

strsignai — Returns string describing signal 

SYNOPSIS 

#include <string.h> 

char *strsignal(int sig); 

extern const char * const sys_si glist [] 


DESCRIPTION 

T he strsignai) ) function returns a string describing the signal number passed in the argument s i g. The string can only be 
used until the next call to strsignai)). 

Thearray sys.si gi i st holds the signal description strings indexed by signal number. 

RETURN VALUE 

The strsignai)) function returns the appropriate description string, or an unknown signal message if the signal number is 
invalid. 


SEE ALSO 

psignal(3), strerror(3) 


GNU, 13 April 1993 


strspn,strcspn 

strspn, strcspn- Search a string for a sdt of characters 

SYNOPSIS 

#include <string.h> 

size t strspn(const char *s, const char ‘accept ); 
size t strcspn(const char *s, const char ‘reject); 

DESCRIPTION 

The strspn)) function calculates the length oftheinitial segment of s, which consists entirely of characters in accept. 

The strcspn)) function calculates the length oftheinitial segment of s, which consists entirely of characters not in rej ect. 



irtod 


RETURN VALUE 

The strspn( ) function returns thenumber of characters in the initial segment of s, which consist only of characters from 

The strcspn( ) function rdturnsthe number of characters in the initial segment of s, which are not in the string rej ect. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

index(3), memchr(3), rindex(3), strchr(3), strpbrk(3), strsep(3), strstr(3), strtok(3) 

12 April 1993 


strstr 

strsti — Locatesa substring 

SYNOPSIS 

#include <string.h> 

char *strstr(const char ‘haystack, const char ‘needle); 

DESCRIPTION 

Thestrstro function finds the first occurrence of the substring n e e d i e in the string hay stack. The terminating \o characters 
are not compared. 

RETURN VALUE 

T he strstr o function returns a pointer to the beginning of the substring, or null if the substring is not found. 

SEE ALSO 

index(3), memchr(3), rindex(3), strchr(3), strpbrk(3), strsep(3), strspn(3), strtok(3) 

GNU, 12 April 1993 


strtod 

strtod — Converts ASC11 string to double 

SYNOPSIS 

#include <stdlib.h> 

double strtod(const char *nptr, char “endptr); 

DESCRIPTION 

Thestrtodf) function converts the initial portion of the string pointed to by nptr to double representation. 

The expected form of the string is optional leading whitespace as checked by isspace(3), an optional plus (+) or minus sign 
(■) followed by asequenceof digitsoptionally containing a decimal point character, optionally followed by an exponent. An 
exponent consists of an e ore, followed by an optional plus or minus sign, followed by a nonempty sequence of digits. If the 
locale is not C or PO SI X, different formats may be used. 
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RETURN VALUES 

The strtod function returns the converted value, if any. 

If endpt r is not null, a pointer to the character after the last character used in the conversion is stored in the location 
referenced by endpt r. 

If no conversion is performed, zero is returned and the value of nptr is stored in the location referenced by endpt r. 

If the correct value would cause overflow, plus or minus huge_val is returned (according to the sign of the value), and erange 
is stored in err no. If the correct value would cause underflow, zero is returned and erange is stored in err no. 

ERRORS 

erange 0 verflow or underflow occurred. 

C0NF0RMST0 

ANSI C 

SEE ALSO 

atof(3), atoi(3), atol(3), strtol(3), strtoul(3) 

BSD man paget 4 M arch 1996 


strtok 

strtok — Extracts token from string 

SYNOPSIS 

#include <string.h> 

char *strtok(char *s , const char *deI i m); 

DESCRIPTION 

A token is a nonempty string of characters not occurring in the string del i m, followed by \o or by a character occurring in 

del i nj, 

Thestrtoko function can be used to parse the strings into tokens. The first call to strtoko should haves as its first 
argument. Subsequent calls should havethefirst argument set to null. Each call returns a pointer to the next token, or null 
when no moretokensarefound. 

If a token ends with a delimiter, this delimiting character is overwritten with a \o and a pointer to the next character is saved 
for the next call to strtok. Thedelimiter string del i m may be different for each call. 

BUGS 

Thisfunction modifies its first argument. The identity of the delimiting character is lost. 

RETURN VALUE 

Thestrtoko function returns a pointer to the next token, or null if there are no more tokens. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

index(3), memchr(3), rindex(3), strchr(3), strpbrk(3), strsep(3), strspn(3), strstr(3) 


GNU, 10 February 1996 
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strtol 

strtoi — C onverts a string to a long integer 

SYNOPSIS 

#include <stdlib.h> 

long int strtol(const char *nptr , char **endptr ,lnt base); 

DESCRIPTION 

Thestrtoio function converts the string in n pt r to a long integer value according to the given base, which must be between 
2 and 36 inclusive or be the special value 0. 

The string must begin with an arbitrary amount of whitespace (as determined by isspace(3)) followed by a single optional + 
or ■ sign. If base iszero or 16, the string may then include a ox prefix, and the number will be read in base 16; otherwise a 
zero base is taken as 10 (decimal) unless the next character isO, in which case it is taken as 8 (octal). 

T he remai nder of the string is converted to a long int value in theobvious manner, stopping at the first character that is not 
a valid digit in the given base (In bases above 10, the letter a in either upper- or lowercase represents 10, b represents 11, and 
so forth, with z representing 35.) 

If endptr is not null, strtoio stores the address of the first invalid character in *endptr. If there were no digits at all, strtoio 
stores the original value of nptr in *endptr. (Thus, if *nptr is not \e but **endptr is \e on return, theentire string isvalid.) 

RETURN VALUE 

Thestrtoio function returns the result of the conversion, unless the value would underflow or overflow. If an underflow 
occurs, strtoio returns long_min. If an overflow occurs, strtoio returns long_max. In both cases, err no is set to erange. 

ERRORS 

erange T he given stri ng was out of range; the value converted has been clamped. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

atof(3), atoi(3), atol(3), strtod(3), strtoul(3) 

BUGS 

Ignores the current locale 

GNU, 10 Junel995 


strtoul 

strtoui— Converts a string to an unsigned long integer. 

SYNOPSIS 

#include <stdlib.h> 

unsigned long int strtoul(const char *nptr, char “endptr, 
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DESCRIPTION 

Thestrtouio function converts the string in nptr to an unsigned long integer value according to the given base, which must 
be between 2 and 36 inclusive, or be the special value 0. 

The string must begin with an arbitrary amount of whitespace (as determined by isspace(3)) followed by a single optional + 
or - sign. If baseiszero or 16, the string may then include a 0 x prefix, and the number will be read in base 16; otherwise, a 
zero base is taken as 10 (decimal) unless the next character is 0, in which case it is taken as 8 (octal). 

The remainder of the string is converted to an unsigned long int value in the obvious manner, stopping at the first character 
that is not a valid digit in the given base (I n bases above 10, the letter a in either upper- or lowercase represents 10, b 
represents 11, and so forth, with z representing 35.) 

If endptr isnotNULL, strtouio stores the address of thefirst invalid character in *endptr. If there were no digits at all, 
strtouio stores the original value of nptr in *endptr. (Thus, if *nptr is not \e but **endptr is\e on return, the entire string is 
invalid.) 

RETURN VALUE 

Thestrtouio function returns either the result of the conversion or, if there was a leading minus sign, the negation of the 
result of the conversion, unless the original (non-negated) value would overflow; in the latter case strtouio returns 
ulongjiax and sets the global variableer r no to erange. 

ERRORS 

erange Thegiven string wasout of range; the value converted has been clamped. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

atof(3), atoi(3), atol(3), strtod(3), strtol(3) 

BUGS 

strtoui ignores thecurrent locale. 

GNU, 29 March 1993 


strxfrm 

strxfrm— String transformation 

SYNOPSIS 

#include <string.h> 

size t strxfrm(char *dest , const char *src, size_t n); 

DESCRIPTION 

The strxf rm( ) function transforms thes re string into a form such that the result of strempo on two strings that have been 
transformed with strxf ™o isthesameasthe result of streolK) on the two strings before their transformation. Thefirst n 
characters of the transformed string are placed in des t . The transformation is based on the program's current locale for 
category lc_collate. (See setiocaie(3)). 

RETURN VALUE 

T he strxf rm() function rdturnsthe number of bytes required to store the transformed string in des t excluding the terminat¬ 
ing \o character. If the value returned is n or more the contents of des t are indeterminate. 



CONFORMSTO 

SVID 3, BSD 4.3, ISO 9899 

NOTES 

The Linux C Library currently hasn't implemented thecompletePOSIX-collating. 

In thePOSIX orC locales strxfrno is equivalent to copying the string with strncpyo. 

SEE ALSO 

bcmp(3), memcmp(3), strcasecmp(3), strcmp(3), strcoll(3), setlocale(3) 

GNU, 12 April 1993 


swab 

swab- Swaps adjacent bytes 

SYNOPSIS 

#include <string.h> 

void swab(const void ‘from, void*to, size_t n); 

DESCRIPTION 

The swabo function copies n bytesfrom thearray pointed to by from to thearray pointed to by to, exchanging adjacent even 
and odd bytes. Thisfunction is used to exchange data between machines that have different low/high byte ordering. 

RETURN VALUE 

The swabo function returns no value 

CONFORMSTO 

SVID 3, BSD 4.3 

SEE ALSO 

bstring(3) 

GNU, 13 April 1993 


sysconf 

sysconf— Gets configuration information at runtime 

SYNOPSIS 

ffinclude <unistd.h> 
long sysconf(int name); 

DESCRIPTION 

sysconf () provides a way for the application to determine values for system limits or options at runtime 

The equivalent macros defined in <unistd.h> can only give conservative values; if an application wants to take advantage of 

values that may change, a call to sysconf o can be made, which may yield more liberal results 

For getting information about a particular file, see f pathconf () or pathconf <). 

Thefollowing values are supported for name. First, the PO SIX.l_compatible values: 
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_SC_ARG_MAX 

_SC_CHILD_MAX 

_SC_CLK_TCK 

_SC_STREAM_MAX 

_SC_TZNAMEJIAX 

_SC_OPEN_MAX 

_SC_JOB_CONTROL 

_SC_SAVED_IDS 

_SC_VERSION 

Next, the PO SIX.2 values: 

_SC_BC_BASE_MAX 
_SC_BC_DIM_MAX 
_SC_BC_SCALE_MAX 
_SC_BC_STRING_MAX 
_SC_COLL_WEIGHTS_MAX 

_SC_EXPR_NEST_MAX 

_SC_LINE_MAX 

_SC_RE_DUP_MAX 

_SC_2_VERSI0N 

_SC_2_DEV 

_SC_2_F0RT_DEV 

_SC_2_F0RT_RUN 


The maximum length of the arguments to theexeco family of 
functions; the corresponding macro is arg_max. 

The number of simultaneous processes per user ID; the corresponding 
macro Is_posix_child_max. 

The number of clock ticks per second; the corresponding macro is 

CLK_TCK. 

The maximum number of streams that a process can have open at any 
time. The corresponding POSIX macro Isstream_max; the 
corresponding standard C macro Isfopenjiax. 

The maximum number of bytes in a time zone name; the 
corresponding macro Istzname_max. 

The maximum number of files that a process can have open at any 
time; the corresponding macro Is_posix_open_max. 

This indicates whether PO SI X-style job control is supported, the 
corresponding macro is_P0six_j0B_c0NTR0L. 
Thisindicateswhetheraprocesshasasaved sfit-user-ID and asaved 
set-group-1 D; the corresponding macro Is_posix_saved_ids. 

Indicates the year and month the POSIX.1 standard was approved in 
theformat yyyymml ; the value 199009L indicates the most recent 
revision, 1990. 


Indicatesthemaximum obase value accepted by the bc(l) utility; the 
corresponding macro Isbc_base_max. 

Indicates themaximum value of elements permitted in an array by 
bc(l); the corresponding macro Isbc_dim_max. 

Indicates the maximum scale value allowed by bc(l); the 
corresponding macro Isbc_scalejiax. 

Indicates the maxi mum length of a string accepted by bc(l); the 
corresponding macro Isbc_stringjiax. 

Indicates the maximum numbers of weights that can be assigned to an 
entry of the lc_collate order keyword in the locale definition file; the 
corresponding macro Iscoll_weights_max. 

Is the maximum number of expressions that can be nested within 
parentheses by expr(l). The corresponding macro is expr_nest_max. 
Themaximum length of a utility's input line length, either from 
standard input or from a file. This includes length for a trailing 
newline The corresponding macro isnNEjiAx. 

Themaximum number of repeated occurrences of a regular 
expression when the interval notation \{m,n\> is used. The value of 
the corresponding macro isREjxjpjiAx. 

Indicates the version ofthePOSIX.2 standard in theformat of 
yyyyhhl . The corresponding macro isposix2_vERSiON. 
lndicateswhetherthePOSIX.2 C language development facilities are 
supported. The corresponding macro isposix2_c_DEv. 
Indicateswhether thePOSIX.2 FORTRAN development utilities are 
supported. The corresponding macro Isposix2_fort_run. 
Indicateswhether the POSIX.2 FORTRAN runtimeutilitiesare 
supported. The corresponding macro Isposix2_fort_run. 
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posix2_localedef Indicates whether the PO SIX.2 creation of locates via iocaie(l) is 

supported. The corresponding macro isposix2_LOCALEDEF. 
_sc_2_sw_dev I ndicates whether the PO SI X .2 software development utilities option 

is supported. The corresponding macro isposix2_sw_DEv. 

RETURN VALUE 

The value returned is the value of the system resource, i if a queried option is available 0 if it is not, or-1 on error. The 
variable err no is not set. 

C0NF0RMST0 

POSIX.1, proposed POSIX.2 

BUGS 

It isdifficult use arg_max because it is not specified how much of the argument space for exec 0 isconsumed by the user's 
environment variables 

Some returned values may be huge; they are not suitable for allocating memory. 

POSIX.2 isnotydtan approved standard; the information in this man page is subject to change 

SEE ALSO 

bc( 1 ), expr(l), locale(l), fpathconf( 3 ), pathconf( 3 ) 

GNU, 18 April 1993 


closelog,openlog,syslog 

cioseiog, openlog, sysiog- Send messages to the system logger 

SYNOPSIS 

#include <syslog.h> 

void openlog( chan *i dent ,int option, int facility); 
void syslog ( int priority, char *f o r ma t , ...); 
void closelog ( void ); 

DESCRIPTION 

cioseiog 0 closes the descriptor being used to write to the system logger. T he use of cioseiog 0 is optional, 
openlog 0 opens a connection to the system logger for a program. The string pointed to by i dent isadded to each message, 
and istypically set to the program name Values for opti on and facility are given in the next subsection. The use of 
openlog) ) is optional; it will automatically be called by sysiog 0 if necessary, in which casei dent will default to null. 
sysiogi ) generates a log message, which will be distributed by sysiogd(8). priority is a combination of ttie facility and the 
level, values for which are given in the next subsection. The remaining arguments are a for mat , as in printf( 3 ) and any 
arguments required by thef or mat , except that the two characters %m will be replaced by the error message string (strerror) 
correspondi ng to the present value of e r r n 0. 

PARAMETERS 

This section lists the parameters used to set the values of opti on, f aci 1 i ty, and priority. 
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OPTION 

The option argument to openiogo isan or of any of these: 

log_cons Write directly to system console if there is an error while sending to system logger 

log_ndelay Open the connection immediately (normally, theconnection isopened when the 

first message is logged) 
log_perror Print to stderr aswell 

log_pid Include pid with each message 


FACILITY 


Thefacility argument is used to specify what type of program is logging the message. This lets the configuration file specify 
that messages from different facilities will be handled differently. 


L0G_AUTH 


Security/authorization messages (deprecated use log_authpriv 
instead) 


LOG_AUTHPRIV 

L0G_CR0N 

L0G_DAEM0N 

L0G_KERN 

log_local0 through 

L0G_L0CAL7 

LOG_LPR 

LOG_MAIL 

LOG_NEWS 

LOG_SYSLOG 

logjjser (default) 

LOG_UUCP 


Security/authorization messages (private) 
Clock daemon (cron and at) 

Other system daemons 
Kernel messages 
Reserved for local use 

Line printer subsystem 

M ail subsystem 

Usenet news subsystem 

M essagesgenerated internally by sysiogd 

Generic user-level messages 

UUCP subsystem 


LEVEL 

This determines the importance of the message 

L0G_EMERG 

L0G_ALERT 

L0G_CRIT 

L0G_ERR 

LOG_WARNING 

L0G_N0TICE 

L0G_INF0 

L0G_DEBUG 


The levels, in order of decreasing importance are 
System is unusable 
Action must betaken immediately 
Critical conditions 
Error conditions 
Warning conditions 
N ormal, but significant, condition 
Informational message 
D ebug-level message 


HISTORY 

A sysiog function call appeared in BSD 4.2. 

SEE ALSO 

logger(l), sysiog.conf(5), syslogd(8) 


Linux, 15 February 1994 
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system 

system—Executes a shell command 

SYNOPSIS 

#include <stdlib.h> 

int system (const char * string); 

DESCRIPTION 

systemo executes a command specified in string by calling /btn/sh -c str i ng, and returns after the command has been 
completed. During execution of the command, sigchld will be blocked, and siGiNTand sigquit will be ignored. 

RETURN VALUE 

The value returned is 127 iftheexecveo call for /btn/sh fails, -1 if there was another error, and the return code of the 
command otherwise 

If the value of string is null, systemo returns non-zero if the shell is available, and zero if not. 
system)) does not affect the wait status of any other children. 

C0NF0RMST0 

ANSI C.POSIX.I, proposed POSIX.2, BSD 4.3 

BUGS 

Do not use systemo from a program with sutd or sgtd privileges, because strange values for some environment variables 
might be used to subvert system integrity. U se the exec(2) family of functions instead, but not execip(2) orexecvp(2). 
The check for the availability of /btn/sh is not actually performed; it is always assumed to be available. 

It is possible for the shell command to return 127, so that code is not a sure indication that the execveo call failed; check 
er rno to makesure 


SEE ALSO 

sh(1), exec(2), signal(2) 


GNU, 13 April 1993 


tan 

tan-Tangent function 

SYNOPSIS 

#include <math.h> 
double tan(double x); 

DESCRIPTION 

Thetano function returns the tangent of x, where x is given in radians 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 
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SEE ALSO 

acos(3), asin(3), atan(3), atan2(3),cos(3),sin(3) 


8Junel993 


tanh 

tanh— H yperbolic tangent function 

SYNOPSIS 

#include <math.h> 
double tanh(double x); 

DESCRIPTION 

T he tanh o function returns the hyperbolic tangent of x, which is defined mathematically as sinh(x) / cosh(x). 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

acosh(3), asinh(3), atanh(3), cosh(3), sinh(3) 

13Junel993 


telldir 

teiidir— Returnscurrent location in directory stream 

SYNOPSIS 

#include <dirent.h> 
off t telldir(DIR *di r); 

DESCRIPTION 

Theteiidiro function returns the current location associated with the directory stream d r . 

RETURN VALUE 

Theteiidiro function returns the current location in the directory stream or -i if an error occurs. 

ERRORS 

ebadf Invalid directory stream descriptor di r 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

opendir(3), readdir(3), closedir(3), rewinddir(3), seekdin(3), scandir(3) 


31 March 1993 
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tempnam 

tempnam— C reates a namefor a temporary file 

SYNOPSIS 

#include <stdio.h> 

char ‘tempnam(const char *dir, const char *pfx); 

DESCRIPTION 

The tempnam) ) function generates a unique temporary filename using up to five characters of pfx, if it is not null. The 
directory to place thefile issearched forin thefollowing order: 

1. Thedirectory specified by theenvironment variableTMPDiR, if itiswritable 

2. Thedirectory specified by the argument di r, if it is not null 

3. Thedirectory specified by p_tmpdtr 

4. Thedirectory \tmp 

The storage for the fi lename is allocated by maiioc o, and so can be freed by the function free o. 

RETURN VALUE 

The tempnamo function returns a pointer to the unique temporary filename, or null if a unique filename cannot be 
generated. 

ERRORS 

eexist Unableto generateauniquefilename 

C0NF0RMST0 

SVID 3, BSD 4.3 

SEE ALSO 

mktemp(3), mkstemp(3), tmpnam(3), tmpfile(3) 

GNU, 3 April 1993 


termios,tcgetattr,tcsetattr, tcsendbreak,tcdrain, tcflush, 
tcflow, cfmakeraw, cfgetospeed, cfgetispeed,cfsetispeed, 
cfsetospeed, tcgetpgrp, tcsetpgrp 

termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, 

cfsetospeed, tcgetpgrp, tcsetpgrp- Get and set terminal attributes, line control, get and si baud rate get and set terminal 
foreground process group ID 

SYNOPSIS 

#include <termios.h> 

#include <unistd.h> 

int tcgetattr ( int fd, struct termios *t e r mi o s _ p ); 

int tcsetattr ( int fd,int optional_actions, struct termios *termios_p ); 

int tcsendbreak ( int fd,int duration ); 

int tcdrain ( int f d ); 

int tcflush ( int f d,int queue_selector ); 




pid_t tcgetpgrp ( int f d ); 

int tcsetpgrp ( int fd, pid_t pgr pid 


DESCRIPTION 

Thetermios functions describe a general terminal interface that is provided to control asynchronous communications ports 

M any of the functions described here have at er mi os.p argument that isa pointer to a termios structure. Thisstructure 

containsthefollowing members: 

tcflag_t c_iflag; /* input modes */ 

tcflag_t c_oflag; /* output modes */ 

tcflag_t c_cflag; /* control modes */ 

tcflag_t c_lflag;/*localmodes*/ 

cc_t c_cc[NCCS]; /* control chars */ 


The c_it lag flag constants are 

ignbrk Ignore break condition on input. 

brkint If ignbrk isnot sdt, generate sigint on break condition, else read break as character \0. 

ignpar Ignore framing errors and parity errors 

parmrk If ignpar is not si, prefix a character with a parity error or framing error with \377 \a. 

If neither ignpar nor parmrk issdt, read a character with a parity error or framing error 
as\B. 

inpck Enable input parity checking. 

istrip Strip off eighth bit. 

inlcr Translate nl to cr on input. 

igncr Ignore carriage return on input. 

icrnl Translate carriage return to newline on input (unless igncr is set). 

iuclc M ap uppercase characters to lowercase on input. 

ixon Enable xon/xoff flow control on output. 

ixany Enable any character to restart output. 

ixoff Enable xon/xoff flow control on input. 

imaxbel Ring bell when input queue isfull. 

The c_ot lag flag constants are 

opost Enable implementation-defined output processing. 

olcuc M ap lowercase characters to uppercase on output. 

onlcr M ap nl to cr-nl on output. 

ocrnl M ap cr to nl on output. 

onocr Don't output cr at column 0. 

onlret D on't output cr. 

ofill Send fill charactersfor a delay, rather than using a timed delay. 

ofdel Fill character is ascii del. If unset, fill character is ascii nul. 

nldly N ewline delay mask. Values are nlo and nli . 

crdly Carriage return delay mask. Values are cro, cri, CR2,or cr3. 
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tabdly H orizontal tab delay mask. V alues are tabo, tabi , tab 2 , tab3 , or xtabs. A value of xtabs 

expands tabs to spaces (with tab stops every eight columns). 
bsdly Backspace delay mask. Values are bso orBsi. 

vtdly Vertical tab delay mask. Values are vto orvn. 

ffdly Form feed delay mask. Values are ffb or ffi . 

The c_ct lag flag constants are 

CSIZE 
CSTOPB 
CREAD 
PARENB 
PARODD 
HUPCL 
CLOCAL 
Cl BAUD 
CRTSCTS 

The c_if lag flag constants are 

isig W hen any of the characters intr, quit, susp, or dsusp are received, generate the 

corresponding signal. 

icanon Enable canonical mode. This enables the special characters eof, eol, eol 2 , erase, kill, 

reprint, status, and werase, and buffers by lines 

xcase If icanon isalso s£, terminal is uppercase only. Input isconverted to lowercase, except 

for characters preceded by \. 0 n output, uppercase characters are preceded by \ and 
lowercase characters are converted to uppercase. 
echo echo input characters 

echoe If icanon isalso set, the erase character erases the preceding input character, and werase 

erases the preceding word. 

echok If icanon isalso set, the kill character erases the current line. 

echonl If icanon isalso set, echo theNL character even if echo is not set. 

echoctl If echo isalso set, ascii control signals other than tab, nl, start, and stop are echoed as 

■x, where x is the character with ASCII code 0x10 greater than the control signal. For 
example character 0x28 (bs) isechoed as “h. 

echoprt If icanon and iecho are also set, characters are printed as they are being erased. 

echoke If icanon isalso set, kill isechoed by erasingeach character on the line, as specified by 

echoe and echoprt. 

flusho Output is being flushed. Thisflag istoggled by typing the discard character. 

noflsh Disableflushing the input and output queues when generating the sigint and sigquit 

signals, and flushing the input queue when generating the sigsusp signal. 
tostop Send thesiGmu signal to the process group of a background process that tries to write 

to its controlling terminal. 

pendin All characters in the input queue are reprinted when the next character is read, (bash 

handles typeahead this way.) 

iexten Enable implementation-defined input processing. 

tcgetattr 0 gets the parameters associated with the object referred by fd and stores them in the termios structure referenced 
by ter mi os. p. T his function may be invoked from a background process; however, the terminal attributes may be 
subsequently changed by a foreground process. 


C haracter size mask. V alues are css, cs6, cs7,or css. 

Set two stop bits, rather than one. 

Enable receiver. 

Enable parity generation on output and parity checking for input. 

Parity for input and output is odd. 

Lower modem control lines after last process closes the device (hang up). 
Ignore modem control lines 
M ask for input speeds (not used). 

Flow control. 
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tcsetattro sets the parameters associated with the terminal (unless support is required from the underlying hardware that is 
not available) from the termios structure referred to by ter mi os.p. optionai_actions specifies when the changes take effect: 
tcsanow T he change occurs immediately. 

tcsadrain T he change occurs after all output written to fd has been transmitted. Thisfunction 

should be used when changing parameters that affect output. 
tcsaflush T he change occurs after all output written to the object referred by fd has been 

transmitted, and all input that has been received but not read will be discarded 
before the change is made 

tcsendbreako transmitsa continuous stream of zero-valued bits for a specific duration, if theterminal is using asynchronous 
serial data transmission. If duration is zero, it transmits zero-valued bits for at least 0.25 seconds, and not more that 0.5 
seconds If duration is not zero, it sends zero-valued bits for duration*N seconds where n is at least 0.25, and not more than 
0.5. 

If theterminal is not using asynchronous serial data transmission, tcsendbreako returns without taking any action. 
tcdrain( (waits until all output written to the object referred to by fd has been transmitted. 

tcfiusho discards data written to the object referred to by fd but not transmitted, or data recaved but not read, depending 
on the value Of queue_selector: 

tciflush Flushes data received but not read 

tcoflush Flushes data written but not transmitted 

tcioflush Flushes both data received but not read, and data written but not transmitted 

tcfiowo suspends transmission or reception of data on theobject referred to by fd, depending on the value of action: 
tcooff Suspends output 

tcoon Restarts suspended output 

tcioff Transmitsa stop character, which stopstheterminal devicefrom transmitting 

data to the system 

tcion T ransmits a start character, which starts the terminal device transmitting data 

to the system 

The default on open of a terminal file is that neither its input nor its output issuspended. 

The baud rate functions are provided for getting and setting the values of the input and output baud rates in the termios 
structure. The new values do not take effect until tcsetattro is successfully called. 

Setting the speed to bo instructs the modem to hang up. The actual bit rate corresponding to B384oo may be altered with 

setserial(8). 

Theinput and output baud rates are stored in thetermios structure, 
cfmakeraw sets the terminal attributes as follows 

termios_p->c_iflag &= '(IGNBRK!BRKINT!PARMRK|ISTRIP 
]INLCR]IGNCR|ICRNL|IXON); 
termios_p->c_oflag &= 'OPOST; 

termios_p->c_lflag &= '(ECHO J ECHONL]ICANON|ISIGjIEXTEN); 
termios_p->c_cflag &= "(CSIZE|PARENB) ; 
termios_p->c_cflag |=CS8; 

cfgetospeedf) returns theoutput baud rate stored in thetermios structure pointed to by termios_p. 

cfsetospeedo sets theoutput baud rate stored in thetermios structure pointed to by termios_p to speed, which must be one 

of these constants: 

BO 

B50 

B75 
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B110 
B134 
B150 


B300 

B600 

B1200 

B1800 

B2400 

B4800 

B9600 

B19200 

B38400 

B57600 

B115200 

B230400 

Thezero baud rate, b@, is used to terminate the connection. If bo is specified, themodem control lines shall no longer be 
asserted. Normally, this will disconnect the line CBAUDExisa mask for the speeds beyond those defined in POSIX.1 (57600 
and above). Thus, B57600 & cbaudex is non-zero, 
cfgetispeedo returns theinput baud rate stored in thetermios structure. 

cfsetispeedo sets theinput baud rate stored in thetermios structure to speed. If theinput baud rate i s set to zero, theinput 
baud rate will be equal to the output baud rate. 

tcgetpgrpo returns process group ID of foreground processing group, or-1 on error. 

tcsetpgrpo sets process group ID to pgrpid. pgrpid must bethelD of a process group in the same session. 

RETURN VALUES 

cfgetispeedo returns theinput baud rate stored in thetermios structure, 
cfgetospeedo returns theoutput baud rate stored in thetermios structure 
tcgetpgrpo returns process group ID of foreground processing group, or-1 on error. 

All other functions return 
0 0 n success 

-1 On failure and set err no to indicate the error 


SEE ALSO 

setserial(8) 


L inux, 2 September 1995 


tmpfile 

tmpfiie— C reates a temporary file 

SYNOPSIS 

#include <stdio.h> 

FILE ‘tmpfile (void); 

DESCRIPTION 

The tmpfile 0 function generates a unique temporary filename using the path prefix p_tmpdir defined in <stdio.h>.The 
temporary file is then opened in binary read/write (w+b) mode. The file will be automatically deleted when it is closed or the 
program terminates. 
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RETURN VALUE 

Thetmpfiieo function returns a stream descriptor, orN ULL if a unique filename cannot be generated or the unique file 
cannot be opened. 

ERRORS 

EACCES 
EEXIST 
EMFILE 
ENFILE 
EROFS 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

mktemp(3), mkstemp(3), tmpnam(3), tempnam(3) 

GNU, 3 April 1993 


Search permission denied for directory in file's path prefix 

Unable to generate a unique filename 

Too many file descriptors in use by process 

Too many files open in system 

Read-only filesystem 


tmpnam 

tmpnam— C reatesa name for a temporary file 

SYNOPSIS 

#include <stdio.h> 
char ‘tmpnam(char *s); 

DESCRIPTION 

Thetmpnamo function generates a unique temporary filename using the path prefix p_tmpdir defined in <stdio.h>. If the 
argument s isNULL, tmpnamo returns the address of an internal static area that holds thefilename which isoverwritten by 
subsequent calls to tmpnam) ). If s isnotNULL, thefilename isreturned ins. 

RETURN VALUE 

T he tmpnamo function returns a pointer to the unique temporary filename, or null if a unique name cannot be generated. 

ERRORS 

eexist Unableto generateauniquefilename 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

mktemp(3), mkstemp(3), tempnam(3), tmpfile(3) 


GNU, 3 April 1993 
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toascii 

toascii— C onverts character to ASC11 

SYNOPSIS 

#include <ctype.h> 
int toascii (int c); 


DESCRIPTION 

toascii o converts c to a 7-bit unsigned char value that fits into the ASC 11 character set, by clearing the high-order bits. 

RETURN VALUE 

The value returned is that of the converted character. 

C0NF0RMST0 

SVID,BSD 

BUGS 

M any people will be unhappy if you use this function. Thisfunction will convert accented letters into random characters 

SEE ALSO 

isascii(3), toupper(3), tolower(3) 

GNU, 16 September 1995 


toupper,tolower 

toupper, tolower- Convert letter to uppercaseor lowercase 

SYNOPSIS 

#include <ctype.h> 
int toupper (int c); 
int tolower (int c); 

DESCRIPTION 

touppero converts the letter c to uppercase, if possible, 
tolowero converts the letter c to lowercase, if possible. 

RETURN VALUE 

The value returned is that of the converted letter, ore if theconversion was not possible 

C0NF0RMST0 

ANSI C, BSD 4.3 

BUGS 

The details of what constitutes an uppercase or lowercase letter depend on the current locale For example, the default locale 
does not know about umlauts, so no conversion is done for them. 

In some non-English locales, there are lowercase letters with no corresponding uppercase equivalent; the German sharp sis 
one example. 
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SEE ALSO 

isalpha(3), setlocale(3), locale(7) 


GNU, 4 April 1993 


tsearch,tfind,tdelete,twalk 

tsearch, tfind, tdeiete, twaik- M anage a binary tree 

SYNOPSIS 

#include <search.h> 

void ‘tsearch (const void ‘key,void “rootp, 

int (‘compar )(const void *, const void *)); 

void ‘tfind (const void ‘key, const void “rootp, 

int (‘compar )(const void *, const void *)); 

void ‘tdelete (const void ‘key,void“r oot p, 

int (‘compar )(const void *, const void *)); 

void twalk (const void ‘root .void (‘act i on)(const void*nodep, 

const VISIT whi ch, 

const int depth)); 

DESCRIPTION 

tsearch, tfind, twaik, and tdelete manage a bi nary tree They are generalized from Knuth (6.2.2) Algorithm T. The first 
field in each node of the tree isa pointer to the corresponding data item. (The calling program must store the actual data.) 
compar points to a comparison routine, which takes pointers to two items It should return an integer that is negative zero, or 
positive depending on whether thefirst item islessthan, equal to, or greater than the second, 
tsearch searches the tree for an item, key points to the item to be searched for. rootp points to a variable that points to the 
root of the tree If the tree is empty, then the variable that rootp points to should beset to null. If the item isfound in the 
tree then tsearch returnsa pointer to it. If it is not found, then tsearch adds it, and returns a pointer to the newly added 
item. 

tfind is like tsearch, except that if the item is not found, then tfind returns null. 
tdeiete deletes an item from the tree Its arguments are the sameas for tsearch. 

twaik performs depth-first, left-to-right traversal of a binary tree, root points to the starting nodeforthetraversal. Ifthat 
node is not the root, then only part of the tree will be visited, twaik calls the user function action each time a node is visited 
(that is, three times for an internal node and once for a leaf), action, in turn, takes three arguments. Thefirst is a pointer to 
the node being visited. The second is an integer that takeson the values preorder, postorder, and endorder depending on 
whether this isthefirst, second, or third visit to the internal node or leaf if it isthesingle visit to a leaf node. (These symbols 
are defined in <search.h>.) The third argument is the depth of the node, with zero being the root. 

RETURN VALUE 

tsearch returnsa pointer to a matching item in the tree, or to the newly added item, or null if there was insufficient memory 
to add the item, tfind returns a pointer to the item, or null if no match isfound. If there are multiple elements that match 
the key, the element returned is unspecified. 

tdeiete returnsa pointer to the parent of the item deleted, or null if the item was not found, 
tsearch, tfind, and tdeiete also return null if rootp wasNULL on entry. 

WARNINGS 

twaik takes a pointer to the root, while the other functions take a pointer to a variable that points to the root. 

twaik uses postorder to mean "after the left subtree but before the right subtree" Some authorities would call this inorder, 

and reserve postorder to mean "after both subtrees." 
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tdeiete frees the memory required for the node in thetree The user is responsible for freeing the memory for the 
corresponding data. 

The example program depends on the fact that twaik makes no further reference to a node after calling the user function 
with argument endorder or leaf. This works with theGN U library implementation, but is not in theSysV documentation. 

EXAMPLE 

Thefollowing program inserts twelve random numbers into a binary tree, then prints the numbers in order. The numbers 
are removed from thetree and their storage freed during the traversal. 

#include <search.h> 

#include <stdlib.h> 

#include <stdio.h> 


void *root=NULL; 

void ‘xmalloc(unsigned n) 


p = malloc(n); 
if(p) return p; 

fprintf(stderr, "insufficient memory\n"); 
exit(1); 


int compare (const void *pa, const void *pb) 

{ 

if(*(int *)pa < *(int *)pb) return -1; 
if(*(int *)pa > *(int *)pb) return 1; 

} 

void action(const void *nodep, const VISIT which, const int depth) 

{ 


switch(which) 


case postorder: 
datap = *(int **)nodep; 
printf("%6d\n", *datap); 

case endorder: 
datap = *(int **)nodep; 
(void)tdelete(datap, &root, compare); 
free(datap); 
break; 
case leaf: 

datap = *(int **)nodep; 

printf("%6d\n", *datap); 

val = tdelete(datap, &root, compare); 

free(datap); 
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int i, *ptr; 
void *val; 

for (i = 0; i < 12; i++) 

ptr = (int *)xmalloc(sizeof(int)); 

*ptr = rand()8.0xff; 

val = tsearch((void *)ptr, &root, compare); 
if(val == NULL) exit(1); 

} 

return 0; 

} 

C0NF0RMST0 

SVID 

SEE ALSO 

qsort(3), bsearch(3), hsearch(3), lsearch(3) 


GNU, 24 September 1995 


ttyname 

ttyname— Returns name of a terminal 

SYNOPSIS 

#include <unistd.h> 
char ‘ttyname ( int desc ); 

DESCRIPTION 

Returns a pointer to the pathname of the terminal device that isopen on the file descriptor desc, or null on error (for 
example, if desc is not connected to aterminal). 

C0NF0RMST0 

POSIX.1 


SEE ALSO 

isatty(3), fstat(3) 


Linux, 20 April 1995 


tzset 

tzset— I nitializes time conversion information 


SYNOPSIS 

#include <time.h> 



DESCRIPTION 

Thetzseto function initializes thetzname variable from theiz environment variable. Thisfunction is automatically called 
by the other time conversion functionsthat depend on thetimezone 

If the tz variable does not appear in the environment, the t z n a me variable is initialized with the best approximation of local 
wall clock time as specified by thetzfiie(5)-formatfile/usr/iib/zoneinfo/iocaitime. 

If the tz variable does appear in the environment but its value is null or its value cannot be interpreted using any of the 
formats specified in thefollowing paragraphs, Coordinated Universal Time(UTC) is used. 

The value of Tzcan be one of three formats. The first format is used when there is no daylight saving time in the local time 
zone: 

std offset 

The std string specifies the name of the time zone and must be three or more alphabetic characters The offset string 
immediately follows std and specifies the time value to be added to the local time to get Coordinated Universal Time 
(UTC). The offset is positive if the local time zone is west of the Prime M eridian and negative if it is east. The hour must be 
between 0 and 24, and the minutes and seconds 0 and 59. 

Thesecond format is used when there is daylight saving time: 

std offset dst [offset],start[/time],end[/time] 

There are no spaces in the specification. The initial std and offset specify the standard time zone as described. The dst 
string and offset specify the name and offsdt for the corresponding daylight savings time zone If the offset is omitted, it 
defaults to one hour ahead of standard time 

The start field specifies when Daylight Savings Time goes into effect and the end field specifies when the change is made 
back to Standard Time. These fields may have thefollowing formats 

jn ThisspecifiestheJ ulian day with n between 1 and 365. February 29 is never counted even in 

leap years. 

n ThisspecifiestheJ ulian day with n between 1 and 365. February 29 iscounted in leap years 

Mm. w.d Thisspecifiesday d (0 <=d <=6) of week w (1 <=w <=5) of month m (1 <=m <= 12). Week 

1 is the first week in which day d occurs and week 5 isthe last week in which day d occurs. 

D ay Oisa Sunday. 

The time fields specify when, in the local time currently in effect, the change to the other time occurs If omitted, the default 
is 02:00:00. 

Thethird format specifies that the time zone information should be read from a file 
:[filespec] 

If the file specification filespec isomitted, the time zone information is read from /usr/iib/zoneinfo/iocaitime, which isin 
tzfiie(5) format. If filespec isgiven, it specifies an-other tzfiie(5)-format file to read the time zone information from. If 
filespec doesnot begin with a/, the file specification is relative to the system time conversion information directory /usr/ 
lib/zoneinfo. 

FILES 

/usr/iib/zoneinfo System time zone directory 

/usr/iib/zoneinfo/iocaitime Local time zonefile 

/usr/lib/zoneinfo/posixrules Rulesfor PO SI X-Style TZS 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3 
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SEE ALSO 

date(l), gettimeofday(2), time(2), ctime(3), getenv(3), tzfile(5) 


BSD, 2July 1993 


none 

none— U ndocumented library functions 

SYNOPSIS 

Undocumented library functions 

DESCRIPTION 

This man page mentions those library functions that are implemented in thestandard libraries but not yet documented in 
man pages. 

SOLICITATION 

If you have information about these functions, please look in the source code, write a man page (using a style similar to that 
of the other Linux section 3 man pages), and send it to aeb@cwi.ni for inclusion in the next man page release. 

THE LIST 

des_setparity, dn_skipname, ecb_crypt, encrypt, endnetgrent, endrpcent, endutent, execlp, fcrypt,fp_nquery,fp_query, 
fp_resstat, getjnyaddress, getnetgrent, getnetname, getopt_long_only, getpublickey, getrpcbyname, getrpcbynumber, 
getrpcent, getrpcport, getsecretkey, getutid, getutline, h_errlist, host2netname, hostalias, inet_nsap_addr, 
inet_nsap_ntoa_init_des, innetgr, key_decryptsession, key_encryptsession, key_gendes, key_setsecret, lfind, libc_nls_init, 
lockf, lsearch, mcheck, memalign, mstats, mtrace, netname2host, netname2user, nlist, obstack_free, p_cdname, p_cdnname, 
p_class, p_fqname, p_option, p_query, p_rr, p_time, p_type, passwd2des, pmap_getmaps, pmap_getport, pmap_rmtcall, pmap_set, 
pmap_unset, putlong, putshort, pututline, rcmd, re_compile_fastmap, re_compile_pattern, rejnatch, re_match_2, re_rx_search, 
re_search, re_search_2, re_set_registers, re_set_syntax, registerrpc, res_send_setqhook, res_send_setrhook, rexec, 
rresvport, rtime, ruserok, ruserpass, setfileno, sethostfile, setkey, setlogmask, setnetgrent, setrpcent, setutent, 
siglongjmp, snprintf, stpcpy, svc_exit, svc_getreq,svc_getreqset, svc_register, svc_run, svc_sendreply, svc_unregister, 
svcerr_auth, svcerr_decode, svcerr_noproc, svcerr_noprog, svcerr_progvers, svcerr_systemerr, svcerr_weakauth, 
svcfd_create, svcraw_create, svctcp_create, svcudp_bufcreate, svcudp_create, svcudp_enablecachesyscall, tdelete, tell, 
tfind, timegm, tr_break, tsearch, twalk, tzsetwall, ufc_dofinalperm, ufc_doit, user2netname, utmpname, valloc, vsnprintf, 
vsyslog, xdecrypt, xdr_accepted_reply, xdr_array, xdr_authdes_cred, xdr_authdes_verf, xdr_authunix_parms, xdr_bool, 
xdr_bytes, xdr_callhdr, xdr_callmsg, xdr_char, xdr_cryptkeyarg, xdr_cryptkeyres, xdr_datum, xdr_des_block, xdr_domainname, 
xdr_double, xdr_enum, xdr_float, xdr_free, xdr_getcredres, xdr_int, xdr_keybuf, xdr_keystatus, xdr_long, xdr_mapname, 
xdr_netnamestr, xdr_netobj, xdr_opaque, xdr_opaque_auth, xdr_passwd, xdr_peername, xdr_pmap, xdr_pmaplist, xdr_pointer, 
xdr_reference,xdr_rejected_reply, xdr_replymsg, xdr_rmtcall_args, xdr_rmtcallres, xdr_short, xdr_string, xdr_u_char, 
xdr_u_int, xdr_u_long, xdr_u_short, xdr_union, xdr_unixcred, xdr_vector, xdr_void, xdr_wrapstring, xdr_yp_buf, 
xdr_yp_inaddr, xdr_ypbind_bindlng, xdr_ypbind_resp, xdr_ypbind_resptype, xdr_ypbind_setdom, xdr_ypdelete_args, 
xdr_ypmapllst, xdr_ypmaplist_str, xdr_yppasswd, xdr_ypreq_key, xdr_ypreq_nokey, xdr_ypresp_all, xdr_ypresp_all_seq, 
xdr_ypresp_key_val, xdr_ypresp_maplist, xdr_ypresp_master, xdr_ypresp_order, xdr_ypresp_val, xdr_ypstat, 
xdr_ypupdate_args, xdrmem_create, xdrrec_create, xdrrec_endofrecord, xdrrec_eof, xdrrec_skiprecord, xdrstdio_create, 
xencrypt, xprt_register, xprt_unregister, yp_all, yp_bind, yp_first, yp_get_default_domain, yp_maplist, ypjnaster, yp_match, 
yp_next, yp_order, yp_unbind, yp_update, yperr_string, ypprot_err 


Linux 1.3.15,25Auguil995 
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usleep 

usieep— Suspends execution for interval of microseconds 

SYNOPSIS 

#include <unistd.h> 

void usleep(unsigned long usee); 

DESCRIPTION 

The usieep o function suspends execution of the calling processor usee microseconds The sleep may be lengthened slightly 
by any system activity or by the time spent processing the call. 

C0NF0RMST0 

BSD 4.3 


SEE ALSO 

setitimer(2), getitimer(2), sleep(3), alarm(3), select(3) 


4 July 1993 


westombs 

westombs— Converts a wide character string to a multibyte character string 

SYNOPSIS 

#include <stdlib.h> 

size_t westombs(char *s, const wchar_t *pwcs , size_t n); 

DESCRIPTION 

T he westombs () function converts a sequence of wide characters from the array pwes into a sequence of multibyte characters 
and stores up to n bytes of multi byte characters i n the array s. 

RETURN VALUE 

westombs o returnsthe number of bytesstored in s or -i if s contains an invalid wide character. 

C0NF0RMST0 

SVID 3, ISO 9899 

SEE ALSO 

mblen(3), mbtowc(3), mbstowcs(3), wctomb(3) 

GNU, 29 March 1993 


wetomb 

wetomb— C onverts a wide character to a multibyte character 

SYNOPSIS 

#include <stdllb.h> 

int wctomb(char *s, wchar_t wchar); 
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DESCRIPTION 

The wctomb o function converts a wide character wchar into a multi byte character and, if s is not null, stores the multibyte 
character representation in s. 

RETURN VALUE 

wctomb o returnsthe number of bytes in the multi byte character or-i if the wide character is not valid. 

C0NF0RMST0 

SVID 3, ISO 9899 

SEE ALSO 

mblen(3), mbstowcs(3), mbtowc(3), wcstombs(3) 

GNU, 29 March 1993 
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Part IV: Special Files 



INTRODUCTION 

This part describes special files 

FILES 

/dev/* Devicefiles 

AUTHORS 

Look at the header of the manual page for the author(s) and copyright conditions Note that these can be different from page 
to page. 

Linux, 24July 1993 


charsets 

charsets— Programmer's view of character sdts and internationalization 

DESCRIPTION 

Linux is an international operating system. Several of its utilities and device drivers (including the console driver) support 
multilingual character sets including Latin-alphabdt letters with diacritical marks, accents, ligatures, and entire non-Latin 
alphabets including G reek. Cyrillic, Arabic, and Hebrew. 

This manual page presents a programmer's-eye view of different character-set standards and how they fit together on Linux. 
Standards discussed include ASCI I, ISO 8859, KOI8-R, Unicode, ISO 2022, and ISO 4873. 


ASCII 

ASCII (American Standard Codefor Information) is the original 7-bit character set, originally designed for American 
English. It is currently described by the EC MA-6 standard. 

An ASCII variant replacing the American crossh atch/octothorpe/h ash pound symbol with the British pound-sterling symbol 
is used in Great Britain; when needed, the American and British variants may be distinguished as U.S. ASCII and U.K. 
ASCII. 

As Linux was written for hardware designed in the U nited States, it natively supports U .S. ASC11. 


ISO 8859 

ISO 8859 is a series of 10 8-bit character sets, all of which have U.S. ASCII in their low (7-bit) half, invisible control 
characters in positions 128 to 159, and 96 fixed-width graphics in positions 160-255. 

Of these, the most important is I SO 8859-1 (Latin-1). It is natively supported in the Linux console driver, fairly well 
supported in X11R6, and is the base character sdt of H TM L. 


Console support for the other 8859 character sets is available under Linux through user-mode utilities (such assetfont(8)) 
that modify keyboard bindings and the EGA graphics table and employ the "user mapping" font table in the console driver. 


H ere are brief descriptions of each set: 


8859-1 (Latin-1) 


8859-2 (Latin-2) 

8859-3 (Latin-3) 
8859-4 (Latin-4) 


Latin-1 covers most W estern European languages such asAlbanian, Catalan, Danish, 
Dutch, English, Faroese Finnish, French, German, Galician, Irish, Icelandic, Italian, 
Norwegian, Portuguese Spanish, and Swedish. The lack of the ligatures Dutch //, 
French oe, and old-style German quotation marks is tolerable. 

Latin-2 supports most Latin-written Slavic and Central European languages; Czech, 
German, H ungarian, Polish, Rumanian, Croatian, Slovak, and Slovene 
Latin-3 is popular with authors of Esperanto, Galician, M altese, and T urkish. 

Latin-4 introduced letters for Estonian, Latvian, and Lithuanian. It is essentially 
obsolete; see 8859-10 (Latin-6). 




charts 


8859-5 


8859-6 


8859-7 

8859-8 

8859-9 (Latin-5) 
8859-10 (Latin-6) 


Cyrillic letters supporting Bulgarian, Byelorussian, M acedonian, Russian, Serbian, and 
Ukrainian. Ukrainians read the letter ghe with downstroke as fieri and would need agrie 
with upstroke to write a correct grie. (See the discussion of KOI8-R in the next 
subsection.) 

Supports Arabic. T he 8859-6 glyph table isa fixed font of separate letter forms, but a 
proper display engine should combine there pairwise into initial, medial, and final 
forms 

Supports modern Greek. 

Supports H ebrew. 

This is a variant of Latin-1 that replaces rarely used Icelandic letters with Turkish ones 
Latin-6 adds the last Inuit (Greenlandic) and Sami (Lappish) letters that were missing in 
Latin 4 to cover the entire N ordic area. RFC 1345 listed a preliminary and different 
Latin 6. Skolt Sami still needs a few more accents than these. 


K0I8-R 

KO18-R isa non-ISO character set popular in Russia. The lower half is U .S. ASCII; the upper is a Cyrillic character set 
somewhat better designed than ISO 8859-5. 

Console support for KO 18-R is available under Linux through user-mode utilities that modify keyboard bindings and the 
EGA graphics table, and that employ the "user mapping" fonttablein the console driver. 

UNICODE 

U nicode (ISO 10646) is a standard that aims to unambiguously represent every known glyph in every human language 
Unicode's native encoding is 32-bit (older versions used 16 bits). Information on Unicode isavailable at http: //www. 

unicode.com. 

Linux represents Unicode using the 8-bit U nicode T ransfer Format (UTF-8). UTF-8 isa variable length encoding of 
U nicode. It uses 1 byte to code 7 bits, 2 bytes for 11 bits, 3 bytes for 16 bits, 4 bytes for 21 bits, 5 bytes for 26 bits, and 
6 bytes for 31 bits. 

Let e, i, x stand for a zero, one, or arbitrary bit. A byte oxxxxxxx stands for the U nicode 00000000 oxxxxxxx, which codes the 
same symbol astheASCII oxxxxxxx. Thus, ASCII goes unchanged into UTF-8, and people using only ASCI I do not notice 
any change- not in code, and not in file size. 

A byteiioxxxxx isthe start of a 2-byte code, and noxxxxx i0yyyyyy isassembled intooooooxxx xxyyyyyy. A bytemoxxxx is 
the start of a 3-byte code, and moxxxx loyyyyyy iozzzzzz isassembled intoxxxxyyyy yyzzzzzz. (When utf-s is used to code 
the 31-bit ISO 10646, then this progression continues up to 6-bytecodes.) 

For ISO-8859-1 users this means that the characters with high bit set now are coded with two bytes This tends to expand 
ordinary text files by one or two percent. T here are no conversion problems however, since the U nicode value of I SO -8859- 
1 symbols equals their ISO-8859-1 value (extended by eight leading zero bits). For Japanese users this meansthat the 16-bit 
codesnow in common use will take three bytes and extensive mapping tables are required. M any Japanese therefore prefer 
iso 2022. 

Note that UTF-8 isself-synchronizing: i@xxxxxx is a tail, any other byte isthe head of a code. Note that the only way ASC 11 
bytes occur in a UTF-8 stream is as themselves In particular, there are no embedded nuls or/s that form part of some larger 
code. 

BecauseASCII, and, in particular, nul and /, are unchanged, the kernel does not notice that UTF-8 is being used. It does not 
care at all what the bytes it is handling stand for. 

Rendering of U nicode data streams is typically handled through subfont tables that map a subset of U nicode to glyphs. 
Internally, the kernel uses Unicode to describe the subfont loaded in video RAM . This means that in UTF-8 mode one can 
use a character set with 512 different symbols This is not enough for Japanese, Chinese, and Korean, but it isenough for 
most other purposes 
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ISO 2022 AND ISO 4873 

The I SO 2022 and 4873 standards describe a font-control model based on VT100 practice. This model is (partially) 
supported bytheLinux kernel and byxtern(l). It is popular in Japan and Korea. 

There are four graphic character sets, called GO, Gl, G2, and G3, and oneofthem isthe current character set for codes with 
high bit zero (initially GO), and oneofthem is the current character sdt for codes with high bit one (initially Gl). Each 
graphic character set has 94 or 96 characters, and is essentially a 7-bit character set. It uses codes either 040-0177 (041-0176) 
or 0240-0377 (0241-0376). GO always has size 94 and uses codes 041-0176. 

Switching between character sdts is done using the shift functions A N (soonsi), A 0 (si or ls©), esc n (ls 2 ), esc 0 (LS3), esc 
n (SS2), 

esc 0 (SS3 ), esc ' (lsir), esc } (ls 2 r), esc | (ls3r). The function LSn makes character sdt Gn the current one for codes with 
high bit zero. The function LSnR makes character sdtGn the current one for codes with high bitone. The function ssn makes 
character set G n (n=2 or 3) the current one for the next character only (regardless of the value of its high order bit). 

A 94-character set is designated as Gn character set by an escape sequence esc < xx (for G 0), esc ) xx (for G1), esc * xx(for 
G 2), esc + xx (for G 3), where xx isa symbol or a pair of symbols found in the I SO 2375 I nternational Register of C oded 
Character Sdts For example, esc ( @ selects the I SO 646 character sdt as GO, esc ( a selects the U.K. standard character set 
(with pound instead of number sign), esc ( b selects ASCI I (with dollar instead of currency sign), esc ( m selects a character 
set for African languages, esc ( i a selects the C uban character set, and so on. 

A 96-character set is designated as Gn character set by an escape sequence esc - xx (for G1), esc . xx (for G 2) or esc / xx 
(for G 3). For example esc - g selects the FI ebrew alphabet asGl. 

A multibyte character set is designated asGn character sdt by an escape sequence esc $ xx or esc $ ( xx (for GO), esc $ ) 
xx (for G1), esc $ * xx (for G 2), esc $ + xx (for G 3). For example, esc $ ( c selects the Korean character set for GO. The 
Japanese character set selected by esc $ b has a more recent version selected by esc & @esc $b. 

ISO 4873 stipulates a narrower use of character sets, where GO isfixed (always ASCI I), so that Gl, G 2, and G 3 can only be 
invoked for codes with the high order bit set. I n particular, A N and A 0 are not used anymore esc ( xx can be used only with 
xx=B, and esc ) xx, esc * xx, esc + xx are equivalent to esc - xx, esc . xx, and esc / xx, respectively. 


SEE ALSO 

console(4), console_ioctl(4), console_codes(4) 


Linux, 5 N member 1996 


console 

console— Console terminal and virtual consoles 

DESCRIPTION 

A Linux system has up to 63 virtual consoles (character devices with major number 4 and minor number 1 to 63), usually 
called /dev/ttyn with 1 n 63. The current console is also addressed by /dev/consoie or /dev/tty0,thecharacter device with 
major number 4 and minor number 0. The device files /dev/* are usually created using the script makedev, or using mknod(l), 
usually with mode 0622 and owner root. tty. 

Before kernel version 1.1.54, thenumber of virtual consoles was compiled into the kernel (in tty.h: #define nr_consoles a) 
and could be changed by editing and recompiling because version 1.1.54 virtual consoles are created on-the-fly, as soon as 
they are needed. 

Common ways to start a process on a console are the following: 

■ Tell intt(8) (in intttab(5)) to start a getty(8) on the console 

■ Ask open(l) to start a process on the console 

■ Start x; it will find thefirst unused consoleand display its output there. (There isalso the ancient dosheii(8).) 
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Common ways to switch consols are the following: 

■ UseAlt4fn orCtrUAIt-tfn to switch to console n; AltGr+Fn might bring you to console n+12 [here Alt and AltGr refer 
to the left and right Alt keys, respectively] 

■ UseAlt-tRightArrow or Alt+LeftArrow to cycle through the presently allocated consols 

■ Usetheprogram chvt(l). (The key mapping can be set by the user; see loadkeys(l); the preceding key combinationsare 
according to the default settings) 

T he command disaiioc(8) will free the memory taken by the screen buffersfor consols that no longer have any associated 
process 


PROPERTIES 

C onsols carry a lot of state. I hope to document that some other time. T he most i mportant fact is that the consols simulate 
vtlOO terminals. In particular, a console is reset to the initial state by printing the two characters ESC c. All escape sequencs 
can be found in console codes(4). 

FILES 

/dev/console 

/dev/tty* 

SEE ALSO 

charsets(4), console_codes(4), console_ioctl(4), mknod(l), tty(4), ttys(4), getty(8), init(8), chvt(l), open(l), disalloc(8), 
loadkeys(l), resizecons(8), setfont(8), mapscrn(8) 

Linux, 31 October 1994 


console_codes 

consoie_codes— Linux console escape and control sequencs 

DESCRIPTION 

The Linux console implements a large subset of the VT102 and ECM A-48/ISO 6429/ANSI X3.64 terminal controls, plus 
certain private-mode sequencs for changing the color palette, character-set mapping, and soon. In thefollowing tabular 
descriptions, the second column givsECM A-48 or DEC mnemonics (the latter if prefixed with DEC) for the given 
function. Sequencs without a mnemonic areneither EC M A-48 nor VT 102. 

After all the normal output processing has been done and a stream of characters arri vs at the console driver for actual 
printing, the first thing that happens is a translation from the code used for processing to the code used for printing. 

If the console is in UTF-8 mode, then the incoming byts are first assembled into 16-bit U nicode cods. Otherwise each 
byte is transformed according to the current mapping table (which translats it to a U nicode value). (See the "C haracter Sets" 
subsection for discussion.) 

In the normal case the Unicode value is converted to a font index, and thisisstored in video memory, so that the corre 
sponding glyph (as found in video ROM ) appears on the screen. Note that the use of Unicode (and the design of the PC 
hardware) allows the use of 512 different glyphs simultaneously. 

If the current U nicode value is a control character, or you are currently processing an escape sequence, the value will treated 
specially. I nstead of being turned into a font index and rendered as a glyph, it may trigger cursor movement or other control 
functions (See the "Linux ConsoleControls" subsection.) 

It is generally not good practice to hardwire terminal controls into programs. Linux supports a terminfo(5) database of 
terminal capabilities Rather than emitting console escape sequences by hand, you will almost always want to use a 
terminfo-aware screen library or utility such asncurses(3), tput(l), or reset(l). 
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LINUX CON SOLE CONTROLS 

This section describes all the control characters and escape sequences that invoke special functions (that is, anything other 
than writing a glyph at the current cursor location) on the Linux console 

CONTROL CHARACTERS 

A character is a control character if (before transformation according to the mapping table) it has one of the 14 codes 00 
(nul), 07 (bel), 08 (bs), 09 (ht), 0a (lf), 0b (vt), 0c (ff), 0d (cr), 0e (so), 0f (si), is (can), ia(suB), ib(ESc), 7f (DEL).Onecan 
set a display control characters mode (see below), and allow 07,09 , 0b, 18 , 1 a, 7f to be displayed as glyphs 0 n the other 
hand, in UTF-8 mode all codes 00-if are regarded as control characters, regardless of any display control characters mode. 
If you haveacontrol character, itisacted upon immediately and then discarded (even in the middle of an escape sequence) 
and the escape sequence continues with the next character. (However, esc starts a new escape sequence possibly aborting a 
previous unfinished one and can and sub abort any escape sequence) The recognized control characters are bel, bs, ht, lf, 
vt, ff, cr, so, si, can, sub, esc, del, csi. They do what one would expect: 


BEL (0X07 

"g) beeps. 



BS (0X08, 

h) backspaces one column (but not past the begim 

ning of the line). 

HT (0X09, 

1) goes to the next tab stop or to the end of the lir 

e if there is no earlier tab stop. 

LF (0X0A, 

j), vt (ox0B, ”k) and ff (0x0c, “l) all give a 

linefeed. 

CR (0X0D, 

m) gives a carriage return. 



SO (0X0E, 

n) activates the G1 character set, and if lf 

nl (new 

line mode) is sdt, also a carriage retu 

SI (0X0F, 

0) activates the G 0 character set. 




can ( 0 xi 8 , “x) and sub (bxia, "z) interrupt escape sequences 

esc ( 0 x 1 b, ■[) starts an escape sequence 

del (0x7f) is ignored. 

csi (0x9b) is equivalent to esc [. 


Reset. 

Linefeed. 

Newline. 

Sdt tab stop at current column. 

Reverse linefeed. 

DEC private identification. The kernel returnsthe string 
esc [ ? 6 c, claiming that it isaVT 102. 

Save current state (cursor coordinates, attributes, character 
sets). 

Restore most recently saved state. 

Control sequence introducer. 

Start sequence selecting character set. 

Select default (I SO 646/I SO 8859-1). 

Select UTF-8. 

Select UTF-8 (obsolete). 

D EC screen alignment test: fill screen with Es. 

Start sequence defining GO character set. 

Select default (ISO 8859-1 mapping). 

Select vtlOO graphics mapping. 
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esc > 
esc = 


ESC ] 


Select null mapping— straight to character RO M . 

Select user mapping, the map that is loaded by the utility 
mapscrn(8). 

Start sequence defining G1 (followed by one of b, 0 , u, k, as 
above). 

decpnm Set numeric keypad mode 

decpam Set application keypad mode. 

osc (Should be: 0 perating system command) esc ] p nrrggbb: 

set palette, with parameter given in 7 hexadecimal digits 
after thefinal p :-(. Heren is the color (0-16), and rrggbb 
indicates the red/green/blue values (0-255). esc ] r: reset 
palette. 


ECMA-48 CSI SEQUENCES 

csi (or esc [) isfollowed by a sequence of parameters, at most npar(16), that are decimal numbers separated by semicolons. 
An empty or absent parameter is taken to beo. The sequence of parameters may be preceded by a single question mark. 

H owever, after csi [(or esc [ [) a single character isread and thisentire sequence is ignored. (Theidea isto ignorean 
echoed function key.) 

Theaction of acsi sequence isdetermined by its final character. 


Character Function Description 


ICH 

cuu 

CUD 

CUF 

CUB 

CNL 

CPL 

CHA 

CUP 

ED 


EL 


IL 

DL 

DCH 

ECH 

HPR 

DA 

VPA 

VPR 

HVP 


Insert the indicated #of blank characters. 

M ove cursor up the indicated #of rows. 

M ove cursor down the indicated #of rows. 

M ove cursor right the indicated #of columns 
M ove cursor left the indicated #of columns 
M ove cursor down the indicated #of rows, to column 1. 
M ove cursor up the indicated #of rows, to column 1. 

M ove cursor to indicated column in current row. 

M ove cursor to the indicated row, column (origin at 1,1). 
Erase display (default: from cursor to end of display). 
esc [ 1 j: erase from start to cursor. 
esc [ 2 j: erase whole display. 

Erase line (default: from cursor to end of line). 
esc [ 1 k: erase from start of line to cursor. 
esc [ 2 k: erase whole line. 

Insert the indicated #of blank lines. 

Delete the indicated #of lines. 

D elete the indicated #of characters on the current line. 
Erase the indicated #of characterson the current line. 

M ove cursor right the indicated #of columns 
AnaveTESC [ ? 6 c: 'I am a VT102 1 . 

M ove cursor to the indicated row, current column. 

M ove cursor down the indicated #of rows. 

M ove cursor to the indicated row, column. 


continues 
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Character Function Description 


TBC 


DECSTBM 


W ithout parameter: clear tab stop at the current position. 
esc [ 3 g: dd€teall tab stops 
Set mode 
Reset mode. 

Set attributes 
Status report. 

Set keyboard LEDs. 

esc [ 0 q: clear all LEDs 

esc [ i q: set Scroll Lock LED 

esc [ 2 q: set N urn Lock LED 

esc [ 3 q: set Caps Lock LED 

Set scrolling region; parameters are top and bottom row. 

Save cursor location. 

Restore cursor location. 

M ove cursor to indicated column in current row. 


EC MA-48 SET GRAPH ICS RENDITION 

TheECM A-48 SGR sequence esc [ <parameters> m sdts display attributes. Several attributes can be set in the same 
sequence. 


Parameter 


25 

27 

30 

32 

33 

35 


Result 

Reset all attributes to their defaults 
Set bold. 

Set half-bright (simulated with color on a color display). 

Set underscore (simulated with color on a color display). 

(The colors used to simulatedim or underline are set using esc ] ....) 

Set blink. 

Sdt reverse video. 

Reset selected mapping, display control flag, and toggle meta flag. 

Select null mapping, set display control flag, reset toggle meta flag. 

Select null mapping, set display control flag, set toggle meta flag. (The toggle meta flag 
causes thehigh bit of a byte to be toggled before the mapping table translation isdone.) 
Set normal intensity. (This is not compatible with ECMA-48.) 

Set normal intensity. 

Underline off. 

Blink off. 

Reverse video off. 

Set black foreground. 

Set red foreground. 

Set green foreground. 

Set brown foreground. 

Set blue foreground. 

Set magenta foreground. 
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36 

37 

38 

39 

40 

42 

43 

45 

46 

47 
49 


Result 

Set cyan foreground. 

Set white foreground. 

Set underscoreon, set default foreground color. 
Set underscore off, set default foreground color. 
Set black background. 

Set red background. 

Set green background. 

Set brown background. 

Set blue background. 

Set magenta background. 

Set cyan background. 

Set white background. 

Set default background color. 


ECMA-48 MODE SWITCHES 

esc [ 3 h deccrm (default off): D isplay control chars 

esc [ 4 h decim (default off): Set insert mode 

esc [ 20 h lf/nl (default off): Automatically follow echo of lf, vt, or ff with cr. 


ECMA-48 STATUS REPORT COMMANDS 

esc [ 5 n Devicestatusreport(DSR): AnswerisESC [ 0 n (Terminal OK). 

esc [ 6 n C ursor position report(CPR):AnswerisESC j y ; x r, where x, y is the cursor 

location. 


D EC PRIVATE MOD EfDECSET/DECRST) SEQ U EN C ES 

These are not described in ECMA-48. The Set M ode sequences are listed; the Reset M ode sequences are obtained by 
replacingthefinal h by x. 


ESC [ ? 1 h 
ESC [ ? 3 h 

ESC [ ? 5 h 
ESC [ ? 6 h 

ESC [ ? 7 h 


ESC [ ? 8 h 
ESC [ ? 9 


ESC [ ? 25 h 
ESC [ ? 1000 h 


decckm (default off): W hen set, the cursor keys send an esc 0 prefix, rather than 
ESC [. 

deccolm (default off =80 columns): 80/132 col mode switch. The driver sources note 
that this alone does not suffice; some user-mode utility such as resizecons(8) has to 
change the hardware registers on the console video card. 
decscnm (default off): Set reverse-video mode. 

decom (default off): W hen set, cursor addressing is relative to the upper left corner of 
thescrolling region. 

DECAWM(default on): Set autowrap on. I n thismode, a graphics character emitted after 
column 80 (or column 132 of deccolm ison) forces a wrap to the beginning of the 
following linefirst. 

decarm (default on): Set keyboard autorepreat on. 

h X10 M ouse Reporting (default off): Set reporting mode to 1 (or reset to 0). 

(See"MouseTracking.") 

deccm (default on): M ake cursor visible 

xii M ouse Reporting (default off): Set reporting mode to 2 (or reset to 0 ). 
(See"MouseTracking.") 
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LINUX CONSOLE PRIVATE CSI SEQUENCES 

The following sequence are neither EC M A-48 nor native VT102. They are native to the Linux console driver. Colors are in 
SGR parameters: 0 = black, 1 = red, 2 = green, 3 = brown, 4 =blue, 5 = magenta, 6 =cyan, 7 = white. 

1 Set color n as the underline color 

1 Set color n asthe dim color 

M ake the current color pair the default attributes 
1 Set screen blank time-out to n minutes 

1 ] Set bell frequency in Hz 

1 ] Set bell duration in msec 

1 ] Bring specified console to the front 

Unblank the screen 
Set the VESA powerdown interval 


CHARACTER SETS 

The kernel knows about four translations of bytes into console-screen symbols. The four tables are 

■ Latinl to PC 

■ VT100 graphics to PC 

■ PC to PC 

■ User-defined 

There are two character sets, called GO and Gl, and one of them isthecurrent character set. (Initially GO.) Typings causes 
G1 to become current, ■ 0 causes G 0 to become current. 

These variables go and gi point to a translation table, and can be changed by the user. Initially, they point at the first two 
tables, Latinl to PC and VT100 graphicsto PC, respectively. The sequences esc ( Band esc ( 0 and esc ( u and esc ( k 
cause G 0 to point at the first, second, third, and fourth translation tables in the preceding list, respectively. The sequences esc 
) Band esc ) oandEsc ) u and esc ) k cause gi to point at thefirst, second, third, and fourth translation tables in the 
preceding list, respectively. 

The sequence esc c causes a terminal reset, which is what you want if the screen is all garbled. The oft-advised "echo *v'o" 
will only make G 0 current, but there is no guarantee that G 0 points at the first table. In some distributions there is a program 
reset(l) that just does echo '[c. If your terminfo entry for the console is correct (and hasan entry rsi=c), then tput reset 
will also work. 

T he user-defined mapping table can be set usi ng mapscrn(8). T he result of the mapping isthat if a symbol c is printed, the 
symbols = map[c] is sent to the video memory. The bitmap that corresponds to s isfound in the character rom, and can be 
changed using setfont(8). 

MO USE TRACKING 

The mouse tracking facility is intended to return xterm-cornpatible mouse status reports Because the console driver has no 
way to know the device or type of the mouse, these reports are returned in the console input stream only when the virtual 
terminal driver receives a mouse update ioctl. These ioctls must be generated by a mouse-aware user-mode application such 
asthegpm(8) daemon. 

Parameters for all mouse tracking escape sequences generated byxterm encode numeric parameters in a single character as 
vaiue+ 040 . For example, i isl. The screen coordinate system isl-based. 

Thexi 0 compatibility mode sends an escape sequence on button press encoding the location and the mouse button pressed. 
It is enabled by sending esc [ ? 9 h and disabled with esc [ ? 9 1 . On button press, xterm sends esc [ m bxy (six charac¬ 
ters). H ere b is button 1, and x andy are the x and y coordinates of the mouse when the button was pressed. This is the same 
code the kernel also produces 
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Normal tracking mode (not implemented in Linux 2.0.24) sends an escape sequence on both button press and release. 

M odifier information is also sent. It isenabled by sending esc [ ? 1000 h and disabled with esc [ 1000 1 .0 n button press 
or release, xterm sends esc [ m bxy.Thelowtwo bits of b encodebutton information: 0 =M B1 pressed, i=M B2 pressed, 

2 =M B3 pressed, 3=releasa The upper bits encode what modifiers were down when the button was pressed and are added 
together: 4=Shift, s=M eta, i6=Control. Again, x and y are the x and y coordinates of the mouse event. The upper-left corner 
is (1,1). 

COMPARISO NS WITH OTHER TERMINALS 

M any different terminal types are described, like the Linux console as being VT 100-compatible. Here we discuss differences 
between the Linux console and the two most important others, the DEC VT102 andxterm(l). 

CONTROL-CHARACTER HANDLING 

Thevti 02 also recognized thefollowing control characters 

nul ( 0 x 00 ) was ignored. 

enq ( 0 x 05 ) triggered an answerback message. 

dci ( 0 x 1 1, "Q, xon) resumed transmission. 

dc3 ( 0 x 13 , "s, xoff) caused vtioc to ignore (and stop transmitting) all codes except xoff and xon. 
vri00-like dci/dc3 processing may be enabled by the tty driver. 

The xterm program (in vti 00 mode) recognizes the control characters bel, bs, ht, lf, vt, ff, cr, so, si, esc. 

ESCAPE SEQUENCES 

Thefollowing VT 100 console sequences are not implemented on the Linux console: 


Exape Sequence Function Desuiption 


ESC N 

esc 0 

ESC P 
ESC X 
ESC • 
ESC \ 
ESC * 
ESC + 


55 2 Single shift 2. (Select G 2 character set for the next 
character only.) 

553 Single shift 3. (Select G 3 character set for the next 
character only.) 

dcs D evice control string (ended by esc \). 

sos Start of string. 

pm Privacy message (ended by esc\). 

st String terminator. 

DesignateG2 character set. 

DesignateG3 character set. 


The program xterm (in vtioo mode) recognizes esc c, esc # 8, esc >, esc =, esc d, esc e, esc h, esc m, esc n, esc 0 , esc p 
... esc esc z (it answers esc [ ? 1 ; 2 c, "I am a vtlOO with advanced video option") and esc * ... esc with the same 
meanings as indicated above. It accepts esc (, esc ), esc *, esc + followed by 0 , a, b for the dec special character and line 
drawing set, uk, and usascii, respectively. ItacceptSESC ] for the setting of certain resources: 


ESC ] 0 ; txt BEL 
ESC ]1 ; txt BEL 
ESC ] 2 ; txt BEL 
ESC ] 4 6 ; name BEL 
ESC ] 5 0 ; fn BEL 


Sdt icon name and window title to txt. 

Sdt icon name to txt. 

Set window title to txt. 

Change log file to name (normally disabled by a compile-time option). 
Set font to f n. 


It recognizes thefollowing with slightly modified meaning: 

Save cursor 
Restore cursor 


ESC 7 DECSC 
ESC 8 DECRC 
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It also recognizes 

ESC F 

ESC 1 

ESC m 

ESC n LS2 

ESC 0 LS3 

ESC j LS3R 

ESC g LS2R 

ESC ' LS1R 

It does not recognize esc % ... 

CSI SEQUENCES 

Thexterm program (as of xFree86 3.1.2G) does not recognize the blink or invisible-mode SGRs Stock X11R6 versionsdo 
not recognize the color-setting SGRs. All other ECM A-48 csi sequences recognized by Linux are also recognized by xterm, 
and vice versa. 

Thexterm program will recognize all of the D EC Private M ode sequences listed earlier, but none of the Linux private-mode 
sequences For discussion ofxterm'sown private-mode sequences, refer to thexterm Control Sequences document by Edward 
M oy and Stephen Gildea, available with thex distribution. 

BUGS 

In 2.0.23, csi is broken, and nul isnot ignored inside escape sequences 

SEE ALSO 

console(4), console_ioctl(4), charsets(4) 

Linux, 31 October 1996 


C ursor to lower-left corner of screen (if enabled by the 
hpLowerleftBugCompat resource). 

M emory lock (per FI P terminals). Locks memory above the 
cursor. 

M emory unlock (per H P terminals). 

Invoke the G 2 character set. 

Invoke the G 3 character set. 

Invoke the G 3 character set as gr. 

FI as no visible effect in xterm. 

Invoke the G 2 character set as gr. 

FI as no visible effect in xterm. 

Invoke the G1 character set asGR. 

FI as no visible effect in xterm. 


console ioctls 

console ioctis—Ioctls for console terminal and virtual consoles 

DESCRIPTION 

Thefollowing Linux-peculiar iocti() requests are supported. Each requires a third argument, assumed hereto beargp. 


WARNING 


If you use thefollowing information, you are going to burn yourself. I octls are undocumented Linux internals, liable to 
be changed without warning. UsePOSIX functions. 
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KDGETLED 


KDSETLED 


KDGKBLED 


KDSKBLED 


KDGKBTYPE 

KDADDIO 

KDDELIO 

KDENABIO 

KDDISAB10 

KDSETMODE 


KDGETMODE 

KDMKTONE 


KIOCSOUND 


GIO_CMAP 

PIO_CMAP 


GIO_FONT 


Get state of LEDs argp points to a long int. The lower three bits of *argp are set to 

the state of the LEDs, as follows: 

led_cap 0x04 caps lock LED 

lec_num 0 x 02 num lock LED 

led_scr 0 x 0 i scroll lock LED 

Sdt the LEDs. The LED sare set to correspond to the lower three bits of ar-gp. 
However, if a higher order bit issdt, the LEDs revert to normal, displaying the state 
of the keyboard functions of caps lock, num lock, and scroll lock. 

Before 1.1.54, theLEDsjust reflected the state of the corresponding keyboard flags 
and kdgetled/kdsetled would also change the keyboard flags Since 1.1.54 the LEDs 
can be made to display arbitrary information, but by default they display the 
keyboard flags T he following two ioctls are used to access the keyboard flags. 

Get keyboard flags CapsLock, NumLock, ScrollLock (not lights), argp points to a char 
that is set to the flag state The low order three bits (mask 0 x 7 ) get the current flag 
state, and the low order bits of the next nibble (mask 0 x 70 ) get the default flag state 
(since 1.1.54). 

Set keyboard flags CapsLock, NumLock, scr-oiiiock (not lights), argp has the desired 
flag state. The low order three bits (mask 0 x 7 ) have the flag state and the low order 
bits of the next nibble (mask 0 x 70 ) have the default flag state (since 1.1.54). 

Get keyboard type This returns the value kb 101 , defined as 0 x 02 . 

Add I/O port as valid. Equivalent to ioperm(arg,i,i). 

D elete I/O port as valid. Equivalent to ioperm(arg,i,0). 

Enable I/O to video board. Equivalent to ioperm(0x3b4, 0x3df-0x3b4+i, i). 

D isable I/O to video board. Equivalent to ioperm(0x3b4, 0x3df-0x3b4+ 1 , 0 ). 

Set text/graphics mode, argp is one of these: 

KD_TEXT 0X00 

KD_GRAPHICS 0x01 

Get text/graphics mode argp points to a long which issetto one of the above values. 
G enerate tone of specified length. T he lower 16 bits of argp specify the period in 
clock cycles, and the upper 16 bits give the duration in msec. If the duration is zero, 
the sound is turned off. Control returns immediately. For example, argp = (i25«i6) 
+ 0x637 would specify the beep normally associated with actri-G. 

Start or stop sound generation. T he lower 16 bits of argp specify the period in clock 
cycles (that is, argp = 1193180/frequency), argp = 0 turns sound off. In either case 
control returns immediately. 

Get the current default color map from kernel, argp points to a 48-byte array. 

(Since 1.3.3.) 

Change the default text-mode color map. argp points to a 48-byte array that 
contains, in order, the red, green, and blue values for the 16 available screen colors 0 
is off, and 255 isfull intensity. The default colors are in order: black, dark red, dark 
green, brown, dark blue dark purple, dark cyan, light grey, dark grey, bright red, 
bright green, yellow, bright blue, bright purple, bright cyan, and white (Since 
1.3.3.) 

Gets 256-character screen font in expanded form, argp points to an 8192-byte array. 
Fails with error code einval if the currently loaded font is a 512-character font, or if 
the console is not in text mode 
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GIO_FONTX 


PIO_FONTRESET 

GIO_SCRNMAP 

GIOJJNISCRNMAP 


PIO_SCRNMAP 

PIO_UNISCRNMAP 


GIO_UNIMAP 


PIO_UNIMAP 


Gets screen font and associated information, argp points to a struct consoietontdesc 
(see pio_fontx). 0 n call, the charcount field should be set to the maximum number 
of characters that would fit in the buffer pointed to by chardata. 0 n return, the 
charcount and charhetght are filled with the respective data for the currently loaded 
font, and the chardata array containsthefont data if the initial value of charcount 
indicated enough space was available: otherwise the buffer isuntouched and errno is 
set to enomem. (Since 1.3.1.) 

Sdts 256-character screen font. Load font into the EGA/VGA character generator, 
argp points to a 8192-byte map, with 32 bytes per character. 0 nly first n of them are 
used for an sxNfont (0 < n <= 32 ). Thiscall also invalidates the Unicodemapping. 
Sets screen font and associated rendering information, argp points to a 
struct consoietontdesc { 
u_short ejSftount; /* characters in font 

(256 or 512) */ 
u_short char height ; /* scan lines per 

character (1-32) */ 
char ‘chardata ; /* font data in 

expanded form */ 


If necessary, the screen will be appropriately resized, andsiGwiNCH sent to the 
appropriate processes. Thiscall also invalidates the Unicode mapping. (Since 1.3.1.) 
Resets the screen font, size, and U nicode mapping to the bootup defaults, argp is 
unused, but should beset to null to ensure compatibility with future versions of 
Linux. (Since 1.3.28.) 

Get screen mapping from kernel, argp points to an area of size e_tabsz, which is 
loaded with the font positions used to display each character. Thiscall is likely to 
return useless information if the currently loaded font is more than 256 characters. 
Get full Unicode screen mapping from kernel, argp points to an area of size 
E_TABSz*sizeof (unsigned short), which is loaded with the U nicodes each character 
represent. A special set of U nicodes, starting at u+foog, are used to represent "direct 
to font" mappings (Since 1.3.1.) 

Loads the user-definable (fourth) tablein the kernel that mapsbytesinto console 
screen symbols argp points to an area of size e_tabsz. 

Loads the user-definable (fourth) tablein the kernel that mapsbytesinto Unicodes 
which are then translated into screen symbols according to thecurrently loaded 
U nicode-to-font map. Special U nicodes starting at u+fgoo can be used to map 
directly to thefont symbols (Since 1.3.1.) 

Get U nicode-to-font mapping from kernel, argp points to a 
struct unimapdesc { 
u_short entry_ct; 


where entries points to 


struct unipalr { 
u_short fontpos; 


array of 


(Since 1.1.92.) 

Put U nicode-to-font mapping in kernel, argp points to a 
(Since 1.1.92.) 


unimapdesc. 
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PIOJJNIMAPCLR 


KDGKBMODE 


KDSKBMODE 

KDGKBMETA 


KDSKBMETA 

KDGKBENT 


Clear table, possibly advise hash algorithm, argp pointsto a 
struct unimapinit { 

u short advised hashstep; /* 0 if no opinion */ 
u short advised hashlevel; /* 0 if no opinion */ 

(Since 1.1.92.) 

Gets current keyboard mode, argp pointsto a long, which isset to oneof these: 

K_RAW 0X00 

K_XLATE 0X01 

K_MEDIUMRAW 0X02 

K_UNIC0DE 0x03 

Sdts current keyboard mode, argp is a long equal to oneof the above values 
Getsmeta key handling mode, argp pointsto a long which isset to oneof these: 
k_metabit 0x03 Set high order bit 

k_escprefix 0x04 Escape prefix 

Sdts meta key handling mode argp is a long equal to one of the preceding values 

Gets one entry in key translation table (keycode to action code), argp pointsto a 

struct kbentry { 

u_char kb_table; 

u_char kb_index; 

u_short kb_value; 


with thefirsttwo membersfilled in: kb_tabie selects the key table (0 <= kb_tabie 
<MAX_NR_KEYMAPS), and kb_index isthe keycode (0 <= kb index <NR_KEYS). kb_value is 
set to thecorresponding action code or k_hole if there isno such key, or k_nosuchmap 
if kb_tabie isinvalid. 

kdskbent Setsoneentry in translation table, argp pointsto a struct kbentry. 

kdgkbsent G ets one function key string, argp pointsto a 

struct kbsentry { 
u_char kb_func; 
u_char kb_string[512]; 


kb_string isset to the (NULL-terminated) string corresponding to the kb_functh 
function key action code. 

kdskbsent Sdts one function key string entry, argp pointsto a struct kbsentry. 

kdgkbdiacr Read kernel accent table, argp points to a 

struct kbdiacrs { 
unsigned int kb_cnt; 
struct kbdiacr kbdiacr[256]; 


where kb_cnt isthe number of entries in the array, each of which isa 
struct kbdiacr {u_char diacr, base, result;}; 

kdgetkeycode Read kernel keycode table entry (scan code to keycode). argp pointsto a 

struct kbkeycode {unsigned int scancode, keycode;}; 
keycode isset to Correspond to the given scancode.(89<=scancode <= 255 only. 
Fori <= scancode <= 88, keycode==scancode.) (Since 1.1.63.) 
kdsetkeycode W rite kernel keycode table entry, argp pointsto struct kbkeycode. (Since 1.1.63.) 
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KDSIGACCEPT 


VT_OPENQRY 

VT_GETMODE 


Thecalling process indicates its willingness to accept the signal argp when it is 
generated by pressing an appropriate key combination, (i <= argp <=nsig). 

(See spawn_console() in linux/drivers/char/keyboard.c.) 

Returns thefirst available (nonopened) console argp points to an int that is set to 
the number of the vt (i <= *argp <=max_nr_consoles). 

Get mode of active vt. argp points to a 
struct vt mode { 
char mode;/‘vtmode*/ 

char waitv; /* if set, hang on writes if not active */ 
short relsig; /* signal to raise on release req */ 
short acqsig; t* signal to raise on acquisition */ 
short frsig; /* unused (set to 0) */ 


VT_SETMODE 

VT_GETSTATE 


mode is set to one of these values: 
vt_auto Auto vt switching 

vt_process Processcontrolsswitching 

vt_ackacq Acknowledge avitch 

Set mode Of active vt. argp points to a struct vtjnode. 
Get global vt state info, argp points to a 

ushort v_active; /* active vt */ 
ushort v_signal;/*signalto send*/ 
ushort v_state;/*vtbitmask*/ 


VT_RELDISP 

VT_ACTIVATE 

VT_WAITACTIVE 

VT_DISALLOCATE 

VT_RESIZE 


For each vt in use, the corresponding bit in the v state member is sdt. (Kernels 1.0 
through 1.1.92.) 

Release a display. 

Switch to vt argp (l <= argp <=MAX_NR_C0NS0LES). 

Wait until vt argp has been activated. 

D eal locate the memory associated with vt argp. (Since 1.1.54.) 

Set the kernel's idea of screensize argp points to a 

ushort v_rows;/*#rows*/ 

ushort v_cols;/*#columns */ 

ushort v_scrollsize; /* no longer used */ 


Note that this does not change the video mode See resizecons(8). (Since 1.1.54.) 
vt_resizex Set the kernel's idea of various screen parameters argp points to a 

struct vtconsize { 
ushort v_rows; /* number of rows */ 
ushort vcols; /* number of columns*/ 
ushort v vlin; /* number of pixel rows on screen */ 
ushort v_din; /* number of pixel rows per character */ 
ushort v vcol; /* number of pixel columns on screen */ 
ushort v ccol; /* number of pixel columns per character */ 

}; 

Any parameter may be set to zero, indicating no change, but if multiple parameters 
are set, they must be self-consistent. Note that this does not change the video mode 
See resizecons(8). (Since 1.3.3.) 
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The action of the following ioctls depends on the first byte in thestruct pointed to by argp, referred to here as the subcode. 
T hese are legal only for the superuser or the owner of the current tty. 


TIOCLINUX, subcode=0 

TIOCLINUX, subcodes 
TIOCLINUX, subcode=2 


TIOCLINUX, subcode=3 
TIOCLINUX, subcodes 
TIOCLINUX, subcode=5 

TIOCLINUX, subcode=6 

TIOCLINUX, subcode=7 

TIOCLINUX, subcode=8 


Dump the screen. Disappeared in 1.1.92. (With kernel 1.1.92 or later, read from 
/dev/vcsN or /dev/vcsaN instead.) 

Get task information. Disappeared in 1.1.92. 

Sdt selection, argp points to a 

struct{fchar subcode; short xs, ys, xe, ye; short selmode} 

xs and ys are the starting column and row. xe and ye are the ending column and 

row. (Upper-left corner is rov»=coiumn=i.) seijnode is 0 for character-by-character 

selection, i for word-by-word selection, or 2 for line-by-line selection. The indicated 

screen characters are highlighted and sawed in the static array sd buffer in devices/ 

char/console.c. 

Paste selection. Thecharactersin the selection buffer are written to fd. 

Unblank thescreen. 

Sdts contents of a 256-bit look up table defining characters in a "word", for word- 
by-word selection. (Since 1.1.32.) 

argp points to a char that issetto the value of the kernel variable shift state (Since 
1.1.32.) 

argp points to a char that issetto the value of the kernel variable report mouse. 
(Since 1.1.33.) 

D ump screen width and height, cursor position, and all the character-attribute pairs. 
(Kernels 1.1.67 through 1.1.91 only. W ith kernel 1.1.92 or later, read from /dev/ 
vcsa* instead.) 


TiocLiNux, subcode=9 Restore screen width and height, cursor position, and all the character-attribute 

pairs. (Kernels 1.1.67 through 1.1.91 only. With kernel 1.1.92 or later, write to 
/dev/vcsa* instead.) 

TiocLiNux, subcode=io H andles the power saving feature of the new generation of monitors. VESA screen 

blanking mode isset to argp[l], which governs what screen blanking does: 

0 Screen blan ki ng i s di sabl ed. 

1 The current video adapter register settings are saved, then the 
controller is programmed to turn off the vertical synchronization 
pulses This puts the monitor into standby mode If your monitor has 
an Off_M ode timer, then it will eventually power down by itself. 

2 T he current settings are saved, then both the vertical and horizontal 
synchronization pulses are turned off. This puts the monitor into off 
mode If your monitor has no Off_M ode timer, or if you want your 
monitor to power down immediately when theblanktimer times out, 
then you choose this option. (Caution: Powering down frequently 
will damage the monitor.) (Since 1.1.76.) 


RETURN VALUES 

-1 for error, and errno isset. 

ERRORS 

errno may take on these values: 

ebadf Filedescriptor isinvalid. 

enotty Filedescriptor is not associated with a character special device or the specified 

request does not apply to it. 



EINVAL 

EPERM 


Filedescriptor or argp is invalid. 
Permission violation. 


WARNING 


Do not regard this man page as documentation of the Linux console ioctls. This is provided for the curious only, as an 
alternative to reading the source. Ioctls are undocumented Linux internals, liable to be changed without warning. (And 
indeed, this page moreor less describes the situation as of kernel version 1.1.94; there are many minor and not-so-minor 
differences with earlier versions) 

Very often, ioctls are introduced for communication between the kernel and one particular well-known program (fdisk, 
hdparm, setseriai, tuneip, loadkeys, selection, setfont, and so on), and their behavior will be changed when required by 
this particular program. 

Programs using these ioctls will not be portable to other versions of U NIX, will not work on older versionsof Linux, and 
will not work on future versions of Linux. 

UsePOSIX functions 


SEE ALSO 

kbd_mode(l), loadkeys(l), dumpkeys(l), mknod(l), setleds(l), setmetamode(l), ioperm(2), termios(2), execve(2), fcntl(2), 
charsets(4), console(4), console_codes(4), mt(4), sd(4), tty(4), ttys(4), vcs(4), vcsa(4), mapscrn(8), setfont(8), resizecons(8), 
/usr/inclede/linux/kd.h, /usr/include/linux/vt.h. 

L inux, 18 September 1995 


fd 

fd— Floppy disk device 

CONFIGURATION 

Floppy drives are block devices with major number 2. Typically, they are owned by root.floppy (that is, user root, group 
floppy) and have either mode 0660 (access checking viagroup membership) or mode 0666 (everybody has access). The minor 
numbers encode thedevicetype, drive number, and controller number. For each device type (that is, combination of density 
and track count), there is a base minor number. To this base number, add thedrive's number on its controller and 128 if the 
drive is on the secondary controller. In the following device tables, n represents the drive number. 


WARNING 


If you use formats with more tracks than supported by your drive you may cause it mechanical damage T rying once if 
more tracks than the usual 40/80 are supported should not damage it, but no warranty is given for that. D on’t create 
de/ice entries for those formats to prevent their usage if you are not sure. 




fd 


D rive-independent device files that automatically detect themedia format and capacity are 


Name 


Bass minor # 



fdn 0 

5.25-inch double density device files: 

Name Capac Cyi. 

Sect. 

Heads 

Bass minor # 

fdnd360 

360K 

40 

9 

2 

4 

5.25-inch high density device files: 




Name 

Capac 

Cyi- 

Sect. 

Heads 

Base minor # 

fdnh360 

360K 

40 

9 

2 

20 

fdnh410 

410K 

41 

10 

2 

48 

fdnh420 

420K 

42 

10 

2 

64 

fdnh720 

720K 

80 

9 

2 

24 

fdnh880 

880K 

80 

11 

2 

80 

fdnh1200 

1200K 

80 

15 

2 

8 

fdnh1440 

1440 K 

80 

18 

2 

40 

fdnh1476 

1476K 

82 

18 

2 

56 

fdnh1494 

1494K 

83 

18 

2 

72 

fdnh1600 

1600K 

80 

20 

2 

92 

3.5-inch double density device files: 




Name 

Capac 

cyi. 

Sect. 

Heads 

B ase minor # 

fdnD360 

360K 

80 

9 

1 

12 

fdnD720 

720K 

80 

9 

2 

16 

fdnD800 

800K 

80 

10 

2 

120 

fdnD1040 

1040K 

80 

13 

2 

84 

fdnDI120 

1120K 

80 

14 

2 

88 

3.5-inch high density device files: 




Name 

Capac 

cyi- 

Sect. 

Heads 

Bax minor # 

fdnH360 

360K 

40 

9 

2 

12 

fdnH720 

720K 

80 

9 

2 

16 

fdnH820 

820K 

82 

10 

2 

52 

fdnH830 

830K 

83 

10 

2 

68 

fdnH1440 

1440 K 

80 

18 

2 

28 

fdnH1600 

1600K 

80 

20 

2 

124 

fdnH1680 

1680K 

80 

21 

2 

44 

fdnH1722 

1722K 

82 

21 

2 

60 

fdnH1743 

1743K 

83 

21 

2 

76 

fdnH1760 

1760K 

80 

22 

2 

96 

fdnH1840 

1840K 

80 

23 

2 

116 

fdnH1920 

1920K 

80 

24 

2 

100 
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3.5-inch extra density device files: 


Name Capac. Cyl. Sect. Heads Bass minor# 


fdnE2880 2880K 

fdnCompaQ 2880K 

fdnE3200 3200K 

fdnE3520 3520K 

fdnE3840 3840K 


36 

36 


44 

48 


32 

36 


108 


DESCRIPTION 

fd special files access thefloppy disk drives in raw mode. The following iocti(2) calls are supported by fd devices: 
fdclrprm dears the media information of a drive (geometry of disk in drive). 

fdsetprm sdts the media information of a drive The media information will be lost when the media ischanged. 

fddefprm sdts the media information of a drive (geometry of disk in drive). The media information will not be lost when the 

media ischanged. This will disable autodetection. In order to re-enable autodetection, you have to issue an fdclrprm. 

fdgetdrvtyp displays the type of a drive (name parameter). For formats that work in several drive types, fdgetdrvtyp returnsa 

name that is appropriate for the oldest drive type that supports thisformat. 

fdflush invalidates the buffer cache for thegiven drive 

fdflush invalidates the buffer cache for thegiven drive 

fdsetmaxerrs setstheerror thresholds for reporting errors, aborting the operation, recalibrating, resetting, and reading sector 
by sector. 

fdsetmaxerrs gets the current error thresholds 
fdgetdrvtyp gdts the internal name of the drive. 
fdwerrorclr clears the write error statistics 

fdwerrorget reads the write error statistics These include the total number of write errors the location and disk of thefirst 
write error, and the location and disk of the last write error. Disks are identified by a generation number that is incremented 
at (almost) each disk change. 

fdtwaddle switches the drive motor off for a few microseconds This might be needed in order to access a disk whose sectors 

are too close together. 

fdsetdrvprm sets various drive parameters. 

fdgetdrvprm reads these parameters back. 

fdgetdrvstat gets the cached drive state (disk changed, write protected et al.) 

fdpolldrvstat pollsthe drive and return its state. 

fdgetfdcstat gets the floppy controller state 

fdreset resets the floppy controller under certain conditions 

fdrawcmd sends a raw command to thefloppy controller. 

For more precise information, consult also the <iinux/fd.h> and <linux/fdreg.h>include files as well as the manual page for 
floppy control. 

NOTES 

The various formats allow you to read and write many types of disks. H owever, if a floppy is formatted with a too small 
intersector gap, performance may drop, up to needing a few seconds to access an entire track. T o prevent this, use interleaved 
formats It is not possibleto read floppies that are formatted using GCR (group code recording), which is used by Apple 11 
and M acintosh computers (800K disks). Reading floppies that are hard sectored (one hole per sector, with the index hole 
being a little skewed) is not supported. This used to be common with older 8-inch floppies 
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FILES 

/dev/fd* 

AUTHORS 

Alain Knaff (Aiain.KnaffMmag.fr), David Niemi (niemidc@clark.net), Bill Broadhurst (bbroad@netcom.com). 

SEE ALSO 

floppycontrol(l), mknod(l), chown(l), getfdprm(l), superformat(l), mount(8), setfd-prm(8) 

Linux, 29 January 1995 


hd 

hd-M FM/IDE hard disk device 

DESCRIPTION 

hd* are block devices to access M FM/IDE hard disk drives in raw mode. The master drive on the primary IDE controller 
(major device number 3) ishda; the slave drive is hdb. The master drive of the second controller (major device number 22) is 
hdc and the slave hdd. 

General IDE block device names have the form hdx, or hdxp, where x isa letter denoting the physical drive, and p isa 
number denoting the partition on that physical drive Thefirst form, hdx, is used to address the whole drive. Partition 
numbers are assigned in theorder the partitions are discovered, and only nonempty, nonextended partitionsget a number. 
Flowever, partition numbers 1-4 are given to the four partitions described in the M BR (the primary partitions), regardless of 
whether they are unused or extended. Thus, thefirst logical partition will behdxs. Both DOS-type partitioning and BSD- 
disk label partitioning are supported. You can have at most 63 partitionson an IDE disk. 

For example, /dev/hda refers to all of thefirst IDE drive in thesystem; and /dev/hdb3 refers to the third DOS primary 

partition on the second one 

They are typically created by the following: 

mknod -m 660 /dev/hda b 3 0 
mknod -m 660 /dev/hdal b 3 1 
mknod -m 660 /dev/hda2 b 3 2 


mknod -m 660 /dev/hda8 b 3 8 
mknod -m 660 /dev/hdb b 3 64 
mknod -m 660 /dev/hdbl b 3 65 
mknod -m 660 /dev/hdb2 b 3 66 


mknod -m 660 /dev/hdb8 b 3 72 
chown root.disk /dev/hd* 

FILES 

/dev/hd* 

SEE ALSO 

mknod(l), chown(l), mount(8), sd(4) 


Linux, 17 December 1992 
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ispell 

ispeii— Format of ispeii dictionariesand affix files 

DESCRIPTION 

ispeii(l) requires two files to definethe language that it isspell checking. T hefirst file isa dictionary containing words for 
the language, and the second isan affix file that defines he meaning of special flagsin thedictionary.Thetwo files are 
combined by buiidhash (see speii(l)) and written to a hash file that is not described here. 

A raw ispeii dictionary (either the main dictionary or your own personal dictionary) contains a list of words, one per line. 
Each word may optionally be followed by a slash (/) and one or more flags, which modify the root word as explained later. 

D epending on the options with which ispeii was built, case may or may not be significant in either the root word or the 
flags, independently. Specifically, if thecompile-timeoption capitalization isdefined, case is significant in the root word; if 
not, case is ignored in the root word. If thecompile-timeoption maskbits is set to a value of 32, case is ignored in the flags; 
otherwise case is significant in theflags Contact your system administrator or ispeii maintainerfor more information (or 
use the -w flag to find out). The dictionary should be sorted with the-f flag of sort(l) before the hash file is built; this is 
done automatically by unchiist(l), which is the normal way of building dictionaries 

If the dictionary contains words that have string characters (see the affix file documentation, following), they must be 

written in the format given bythedefstringtype statement in the affix file This will be the case for most non-English 

languages Be careful to use this format, rather than that of your favorite formatter, when adding words to a dictionary. If 

you add words to your personal dictionary during an ispeii session, they will automatically be converted to the correct 

format. Thisfeaturecan be used to convert an entire dictionary if necessary: 

echo qqqqq > dummy.diet 

buiidhash dummy.diet affix-file dummy.hash 

awk 'fprint "*"gENDfprint "#"g' old-dict-file \ 

| ispell -a -T old-diet-string-type \ 

-d ./dummy.hash -p ./new-dict-file \ 

> /dev/null 
rm dummy.* 

T he case of the root word controls the case of words accepted by ispeii, as follows 

1. If the root word appears only in lowercase (for example, bob), it will be accepted in lowercase capitalized, or all capitals. 

2. If the root word appears capitalized (for example Robert), it will not be accepted in all lowercase but will be accepted 
capitalized or all in capitals. 

3. If the root word appears all in capitals (for example, U NIX), it will only be accepted all in capitals 

4. If the root word appears with a "funny" capitalization (for example ITCorp), a word will be accepted only if it follows 
that capitalization, or if it appears all in capitals. 

5. M ore than one capitalization of a root word may appear in thedictionary. F lags from different capitalizati 0 ns are 
combined using or. 

Redundant capitalizations (for example, bob and Bob) will be combined by buiidhash and by ispeii (for personal dictionar¬ 
ies), and can be removed from a raw dictionary by munchiist. 

For example, thedictionary 

Robert 

UNIX 

ITcorp 

ITCorp 

will accept bob, Bob, bob, Robert, robert, unix, ITcorp, iTCorp, and itcorp, and will rqectall others Some of the unacceptable 
forms are hOb, robert, Unix, and Itcorp. 



As mentioned, root words in any dictionary may be extended by flags. Each flag is a single alphabetic character, which 
represents a prefix or suffix that may be added to the root to form a new word. For example, in an English dictionary the d 
flag can be added to bathe to make bathed. Because flags are represented as a single bit in the hashed dictionary, this results 
in significant space savings. Themunchiist script will reduce an existing raw dictionary by adding flags when possible 
When a word is extended with an affix, the affix will be accepted only if it appears in the same case as the initial (prefix) or 
final (suffix) letter of the word. Thus, for example, the entry unix/m in the main dictionary (M means add an apostrophe and 
ansto make a possessive) would accept UN IX'S but would rqect UNIX’s If UN IX’s is legal, it must appear as a separate 
dictionary entry, and it will not be combined by munchiist. (In general, you don't need to worry about these things 
munchiist guarantees that itsoutput dictionary will accept the same set of words as its input, so all you have to do is add 
words to the dictionary and occasionally run munchiist to reduce its size) 

As mentioned, the affix definition file describes the affixes associated with particular flags. It also describes the character set 
used by the language. 

Although the affix-definition grammar is designed foralineoriented layout, it is actually a free-format grammar and can be 
laid out weirdly if you want. Comments are started by a pound (sharp) sign (#), and continue to the end of the line 
Backslashes are supported in the usual fashion (\nnn, plus specials \n, \r, \t, w, \f, \b, and thena/v hex format \xnn). Any 
character with special meaning to the parser can be changed to an uninterpreted token by backslashing it; for example, you 
can declare a flag named asterisk or colon with flag n*: or flag n ::. 

Thegrammarwill be presented in a top-down fashion, with discussion of each element. An affix-definition file must contain 
exactly one table 

table : [headers ] [pr ef i x e s ] [s u f f i x e s ] 

At least one of prefixes and suffixes is required. T hey can appear in either order. 

headers : [opt ions ] char-sets 

The headers describe options global to this dictionary and language. These include the character sets to be used and the 
formatter, and the defaults for certain ispdl flags 

options : { fmtr-stmt | opt - s t nit | flag-stmt | n u m- s t mt } 

Theoptionsstatementsdefinethedefaults for certain ispeii flags and for the character sets used by the formatters. 

fmtr-stmt : { nr of f - st mt | tex-stmt } 

A fmtr-stmt statement describes characters that have special meaning to a formatter. Normally, this statement is not 
necessary, but some languages may have preempted the usual defaults for use as language-specific characters. I n this case, 
these statements may be used to redefine the special characters expected by the formatter. 

nroff-stmt : { nroffchars | troffchars } string 

The nroffchars statement allows redefinition of certain nroff control characters. The string given must be exactly five 
characters long, and must list substitutions for the left and right parentheses, the period, the backslash, and the asterisk. (The 
right parenthesis is not currently used, but is included for completeness.) For example, thestatement: 

nroffchars {}.\\* 

would replace the left and right parentheses with left and right curly braces for purposes of parsing nroff/troff strings, with 
no effect on the others (admittedly a contrived example). Note that the backslash is escaped with a backslash. 

tex-stmt : { TeXchars \ texchars } string 

Theiexchars statement allows redefinition of certain T eX/LaTeX control characters. The string given must be exactly 
thirteen characters long, and must list substitutionsfor the left and right parentheses, the left and right square brackets, the 
left and right curly braces, the left and right angle brackets, the backslash, the dollar sign, the asterisk, the period or dot, and 
the percent sign. For example thestatement: 
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would replace the functions of the left and right curly braces with the left and right angle brackets for purposes of parsing 
TeX/LaTeX constructs, while retaining their functionsfor the tib bibliographic preprocessor. N ote that the backslash, the 
left square bracket, and the right angle bracket must be escaped with a backslash. 

cmpnd- stmt : compoundwords compound-opt 
aff-stmt : allaffixes on-or ■ of f 
on- or-of f : { on | off > 

compound-opt : {on-or-off ] controlled charact er } 

An opt-stmt, used in the preceding code controls certain ispeii defaults that are best made language-specific. The 
aiiaffixes statement controls the default for the -p and -m options to ispeii. If aiiaffixes is turned off (the default), ispeii 
will default to the behavior of the -p flag: root/affix suggestions will only be made if there are no "near misses" If aiiaffixes 
is turned on, ispeii will default to the behavior of the -m flag: root/affix suggestions will always be made. 

The compoundwords statement controls the default for the-Band -c options to ispeii. If compoundwords is turned off (the 
default), ispeii will default to the behavior of the-B flag: run-together words will be reported aserrors. If compoundwords is 
turned on, ispeii will default to the behavior of the-c flag: run-together words will be considered as compounds if both are 
in the dictionary. This is useful for languages such as German and Norwegian, which form large numbers of compound 
words Finally, if compoundwords is set to controlled, only words marked with theflag indicated by character (which should 
not be otherwise used) will be allowed to participate in compound formation. Because this option requires the flags to be 
specified in the dictionary, it isnot available from the command line 

flag-stmt : flagmarker char act er 

Thefiagmarker statement describes the character that is used to separate affix flags from the root word in a raw dictionary 
file. This must be a character that is not found in any word (including in string characters; seefollowing). Thedefault is/ 
because this character isnot normally used to represent special charactersin any language. 

n urn-stmt : compoundmin di gi t 

Thecompoundmin statement controls the length of the two components of a compound word. This only has an effect if 
compoundwords is turned on or if the-C flag is given to ispeii. In that case, only words at least as long as the given minimum 
will be accepted as components of a compound. Thedefault is 3 characters. 

char-sets : norm-sets [ alt-sets ] 

The character-set section describes the characters that can be part of a word, and defines their collating order. There must 
always be a definition of "normal" character sets; in addition, there may be one or more partial definitions of "alternate" sets 
that are used with varioustext formatters. 

norm-sets : [def t y pe ] charset-group 

A "normal" character set may optionally begin with a definition of the file suffixes that make use of this set. Following this 
are one or more character-set declarations 

deft y pe : defstringtype name deformatter suffix* 

T he defStringtype declaration gives a list of file suffixes that should make use of the default string characters defined as part of 
the base character sdt; it is only necessary if string characters are being defined. T he name parameter is a string giving the 
unique name associated with these suffixes; often it is a formatter name. If theformatter is a member of the troff family, 
nroff should be used for the name associated with the most popular macro package; members of theT eX family should use 
tex. 0 ther names may be chosen freely, but they should be kept simple, as they are used in ispeii's -t switch to specify a 
formatter type. The deformatter parameter specifies the deformatting style to use when processing files with thegiven 
suffixes Currently, this must be either tex or nroff. The suffix parameters are a whitespace-separated list of strings which, if 
present at the end of a filename indicate that the associated set of string characters should be used by default for this file. For 
example, the suffix list for the troff family typically includes suffixes such as .ms, .me, .mm, and so on. 




A char-stmt describes single characters; a string-stmt describes characters that must appear together asa string, and which 
usually represent a single character in thetarget language. Either may also describe conversion between uppercase and 
lowercase A dup-stmt isused to describe alternate forms of string characters, so that a single dictionary may be used with 
several formatting programs that use different conventionsfor representing non-ASC 11 characters 

char-stmt : wordchars char acter-range 

i wordchars Iowercase-range uppercase-range 
i boundarychars character-range 

| boundarychars Iowercase-range upper case-range 

St ri ng-stmt : stringchar string 

| stringchar I owercase-str i ng uppercase-stri ng 

Characters described with the boundarychars statement are considered part of a word only if they appear singly, embedded 
between characters declared with thewordchars or stringchar statements. For example if the hyphen is a boundary character 
(useful in French), the string foo-bar would be a single word, but -too would be the same as too, and too-bar would be two 
words separated by nonword characters. 

If two ranges or strings are given in achar-stmt or string-stmt, thefirst describes characters that are interpreted as lowercase 
and the second describes uppercase. I n the case of a stringchar statement, the two strings must be of the same length. Also, 
in a stringchar statement, the actual strings may contain both uppercase and characters themselves without difficulty; for 
instance, the statement: 

stringchar "\\*(sS" "\\*(Ss" 

is legal and will not interfere with (or be interfered with by) other declarations of "s" and “s" as lowercase and uppercase, 
respectively. 

A final note on string characters: some languages collate certain special characters as if they were strings. For example the 
German "a-umlaut" is traditionally sorted as if it were ae. ispeii is not capable of this; each character must be treated as an 
individual entity. So in certain cases, ispeii will sort a list of words into a different order than the standard "dictionary" 
order for the target language. 

al t-sets : al ttype [ al t-stmt *] 

Because different formatters use different notationsto represent non-ASCII characters, ispeii must be aware of the represen¬ 
tations used by these formatters. T hese are declared as alternate sdts of string characters 

alttype : altstringtype name suffix* 

Theaitstringtype statement introduces each set by declaring the associated formatter name and filename suffix list. This 
nameand list are interpreted exactly as in thedefstringtype statement. Following this header are one or more ait-stmts that 
declare the alternate string characters used by this formatter. 

all-stmt : altstringchar al t - st r i ng std-string 

Theaitstringchar statement describes alternate representations for string characters. For example the-mm macro package 
oftroft represents the German "a-umlaut" asa\*:,whileTeX uses the sequence \ ■ a. Ifthetroff versions are declared asthe 
standard versions using stringchar, theTeX versions may be declared as alternates by using the statement: 

altstringchar \\\"a a\\* 

W hen the altstringchar statement is used to specify alternateforms, all forms for a particular formatter must be declared 
together asa group. Also, each formatter or macro package must provide a complete set of characters, both uppercase and 
lowercase and the character sequences used for each formatter must be completely distinct. Character sequences that 
describe uppercase and lowercase versions of thesame printable character must also be the same length. It may be necessary 
to define some new macrosforagiven formatter to satisfy these restrictions. (The current version of buiidhash does not 
enforce these restrictions, but failure to obey them may result in errors being introduced into files that are processed with 

ispeii.) 

An important minor point is that ispeii assumes that all characters declared aswordchars or boundarychars will occupy 
exactly one position on the terminal screen. 
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A single character-set statement can declare either a single character or a contiguous range of characters. A range isgiven as in 
egrep and the shell: [a-z] means lowercase alphabetics; [*a-z] means all but lowercase and soon. All character-set state¬ 
ments are combined (unioned) to produce the final list of characters that may be part of a word. The collating order of the 
characters is defined by the order of their declaration; if a range is used, the characters are considered to have been declared in 
ASCII order. Characters that have case are collated next to each other, with the uppercase character first. 

T he character-declaration statements have a rather strange behavior caused by the need to match each lowercase character 
with its uppercase equivalent. In any given wordchars or boundarychars statement, the characters in each range are first sorted 
into ASCII collating sequence, then matched one-for-onewith the other range. (The two ranges must have the same number 
of characters). Thus, for example the two statements: 

wordchars [aeiou] [AEIOU] 
wordchars [aeiou] [UOIEA] 

would produce exactly the same effect. To get the vowels to match up "wrong," you would have to use separate statements: 

wordchars a U 
wordchars e 0 
wordchars i I 
wordchars o E 
wordchars u A 

which would cause uppercasee to beO, and lowercase 0 to bee. This should normally be a problem only with languages that 
have been forced to use a strange ASCI I collating sequence. If your uppercase and lowercase letters both collate in the same 
order, you shouldn't have to worry about this "feature.” 

T he prefixes and suffixes sections have exactly the same syntax, except for the introductory keyword: 

prefixes : prefixes flagdef* 
suffixes : suffixes flagdef* 
flagdef : flag [*jU] char : repl * 

A prefix or suffix table consists of an introductory keyword and a list of flag definitions. Flags can be defined more than once, 
in which case the definitions are combined. Each flag controls one or more repis (replacements), which are conditionally 
applied to the beginningsor endings of various words. 

Flags are named by a single character char. Depending on a configuration option, this character can be either any uppercase 
letter (the default configuration) or any 7-bit ASC11 character. M ost languages should be able to get along with just 26 flags. 
A flag character may be prefixed with one or more option characters. (If you wish to use one of the option characters as a flag 
character, simply enclose it in double quotes.) 

Theasterisk (*) option meansthat thisflag participates in cross-product formation. Thisonly matters if thefile contains both 
prefix and suffix tables If so, all prefixesand suffixes marked with an asterisk will be applied in all cross-combinations to the 
root word. For example consider the root fix with prefixespre and in, and suffixes es and ed.lf all flags controlling these 
prefixes and suffixes are marked with an asterisk, then the single root fix would also generate prefix, prefixes, prefixed, infix, 
infixes infixed, fix, fixes, and fixed. C ross-product formation can produce a large number of words quickly, some of which 
may be illegal, so watch out. If cross-products produce illegal words, munchiist will not produce those flag combinations, and 
theflag will not be useful. 

repl : condition* > [ - strip-string , ] append-string 

The-option specifies that the associated flag is only active when a compound word is being formed. This is useful in a 
language like German, in which theform of a word sometimes changes inside a compound. 

A repl is a conditional rule for modifying a root word. Up to eight conditions may be specified. If the conditions are 
satisfied, the rules on the rightsideof the repi are applied, asfollows 

1. If a strip-string isgiven, it isfirst stripped from the beginning or ending (asappropriate) of the root word. 

2. The append-string is added at that point. 
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For example, the condition . means"any word", and the condition y means"any word ending in Y."Thefollowing (suffix) 
replacements 

. > MENT 

Y > -Y,IES 

would change induce to inducement and fly to flies. (If they were controlled by the same flag, they would also change flyto 
flyment, which might not be what waswanted. munchiist can be used to protect against this sort of problem; seethe 
command sequence given in the next paragraph.) 

N o matter how much you might want it, the strings on the right must be strings of specific characters, not ranges The 
reasons are rooted deeply in the way ispeii works and it would be difficult or impossible to provide for more flexibility. For 
example, you might want to write: 

[EY] > -|EY],IES 

This will not work. Instead, you must use two separate rules 

e > -E,IES 

Y > -Y,IES 

Theapplication of repiscan be restricted to certain wordswith conditions 

condition : { . | character | range } 

A condition is a restriction on the characters that adjoin, and/or are replaced by, the right-hand side of the repi. Up to 
eight conditions may be given, which should be enough context for anyone. The right-hand s'dewill be applied only 
if the conditions in therepi are satisfied. The conditions also implicitly define a length; roots shorter than the number of 
conditions will not pass the test. (Asa special case, a condition of a single dot definesa length of zero, so that the rule applies 
to all words indiscriminately.) This length is independent of the separate test that insists that all flags produce an output 
word length of at least four. 

Conditions that are single characters should be separated by whitespace. For example to specify words ending in ED, write 
this: 

E D> -ED,ING # As in covered > covering 

If you write this: 

ED > -ED,ING 

the effect will be the same as 

[ED] > -ED,ING 

Asafinal, minor but important point, it issometimes useful to rebuild a dictionary file using an in compatible suffix file. For 
example, suppose you expand the r flag to generate "er" and "ers" (thus making thez flag somewhat obsolete). To build a 
new dictionary newdict that using new affixes will accept exactly the same list of words asthe old list oiddict did using old 
affixes, the -c switch of munchiist is useful, as in the following example: 

$ munchiist -c oldaffixes -1 newaffixes oiddict > newdict 

If you use this procedure, your new dictionary will always accept the same list theoriginal did, even if you badly screwed up 
the affix file This is because munchiist compares the words generated by a flag with theoriginal word list and refuses to use 
any flags that generate illegal words. (Don't forget that the munchiist step takesa long time and eats up temporary file space.) 

EXAMPLES 

As an example of conditional suffixes, here is the specification of the s flag from the English affix file 
flag *S: 

["AEIOUJY > -Y,IES # As in imply > implies 
[AEIOUJY > S # As in convey > conveys 
[ SXZH ] > ES # As in fix > fixes 
[ “SXZHY] > S #As in bat > bats 
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Thefirst lineapplies to wordsending in Y but notin vowel-Y. The second takes care of the vowel-Y words The third then 
handles those words that end in a sibilant or near-sibilant, and the last picks up everything else. 

Note that the conditions are written very carefully so that they apply to disjoint sets of words. In particular, note that the 
fourth line excludes words ending in Y as well asthe obvious SXZH. Otherwise, it would convert "imply" into "implys" 
Although the English affix file does not do so, you can also have a flag generate more than one variation on a root word. For 
example, you could extend the English r flag as follows 

flag *R: 

E > R #As in skate > skater 
E > RS # As in skate > skaters 
["AEIOUJY > -Y,IER # As in multiply > multiplier 
["AEI0U]Y > -Y.IERS # As in multiply > multipliers 
[AEIOUJY > ER # As in convey > conveyer 
[AEIOU]Y > ERS # As in convey > conveyers 
['EY] > ER # As in build > builder 
['EY] > ERS # As in build > builders 

This flag would generate both "skater" and "skaters" from "skate." This capability can be very useful in languages that make 
use of noun, verb, and adjective endings For instance, one could define a single flag that generated all the German "weak" 
verb endings 

SEE ALSO 

ispell(l) 

Local 


ip 

ip— Lineprinter devices. 

SYNOPSIS 

#include <linux/lp.h> 

CONFIGURATION 

ip[02] are character devices for the parallel line printers; they have major number 6 and minor number 02. The minor 
numbers correspond to the printer port base addresses 0x03bc, 0x0378, and 0x0278. Usually, they have mode 220 and are 
owned by root and group ip. You can use printer ports either with polling or with interrupts Interrupts are recommended 
when high traffic isexpected, such as for laser printers. For usual dot matrix printers, polling will usually be enough. The 
default ispolling. 

DESCRIPTION 

Thefollowing iocti(2) calls are supported: 

int ioctl(int fd, LPTIME, int arg) 


int ioctl(int fd, LPCHAR, int arg) 


Sdts the amount of time that the driver sleeps before rechecking the 
printer when the printer's buffer appears to be filled to arg. If you have a 
fast printer, decrease this number; if you have a slow printer, then 
increase it. T his is in hundredths of a second; the default 2 is 0.05 
seconds It only influences the polling driver. 

Sdts the maximum number of busy-wait iterations that the polling driver 
does while waiting for the printer to get ready for receiving a character to 
arg. If printing is too slow, increase thisnumber; if thesystem gets too 
slow, decrease thisnumber. Thedefault is 1000. It only influences the 
polling driver. 
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int ioctl(int fd, LPABORT, int arg) 
int ioctl(int fd, LPABORTOPEN, int arg) 
int ioctl(int fd, LPCAREFUL, int arg) 


int ioctl(int fd, LPWAIT, int arg) 


int ioctl(int fd, LPSETIRQ, int arg) 


int loot Hint fd, LPGETIRQ, int *arg) 
int ioctl(int fd, LPGETSTATUS, int *arg) 

LP_PBUSY 

LP_PACK 

LP_P0UTPA 

LP_PSELECD 

LP_PERRORP 


int ioctl(int fd, LPRESET) 


If arg iso, the printer driver will retry on errors; otherwise it will abort. 

T he default is 0. 

If arg iso, open(2) will be aborted on error; otherwise the error will be 
ignored. The default is to ignore it. 

If arg iso, then the out-of-paper, offline and error signals are required to 
be false on all writes; otherwise they are ignored. The default is to ignore 
them. 

Sdts the number of busy-wait iterations to wait before strobing the printer 
to accept a just-written character and the number of iterations to wait 
before turning the strobe off again to arg. The specification saysthistime 
should be0.5 microseconds but experience has shown the delay caused 
by the code isalready enough. For that reason, thedefault value iso. This 
is used for both the polling and the interrupt driver. 

ThisioctiO requires superuser privileges. Ittakesan int containing the 
new IRQ as argument. As a side effect, the printer is reset. When arg iso, 
the polling driver will be used, which isalso default. 

Stores the currently used IRQ in arg. 

Stores the value of the status port in arg. T he bits have the following 
meaning: 

Inverted busy input, active high 
Unchanged acknowledge input, active low 
Unchanged out-of-paper input, active high 
Unchanged selected input, active high 
U nchanged error input, active low 

Refer to your printer manual for the meaning of the signals N ote that 
undocumented bits can also beset, depending on your printer. 

Resetsthe printer. No argument is used. 


FILES 

/dev/lp* 

AUTHORS 

The printer driver was originally written by Jim Weigand and LinusTorvalds It was further improved by M ichael K. 
Johnson. The interrupt code was written by Nigel Gamble. Alan Cox modularized it. lpcareful, lpabort, lpgetstatus were 
added by ChrisM etcalf. 

SEE ALSO 

mknod(l), chown(l), chmod(l), tunelp(8), lpcntl(8) 

15 January 1995 
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mem, kmem, port— System memory, kernel memory, and system ports 


DESCRIPTION 

mem isa character devicefile that isan image of the main memory of the computer. Itcan be used, for example, to examine 
(and even patch) the system. 
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Byte addresses in mem are interpreted as physical memory addresses. References to non-existent locations cause errors to be 
returned. 

Examining and patching is likely to lead to unexpected results when read-only or write-only bits are present. 

It is typically created by 

mknod -m 660 /dev/mem c 1 1 
chown root.mem /dev/mem 

Thefilekmem isthesarneasmem, except that the kernel virtual memory rather than physical memory is accessed. 

It is typically created by 

mknod -m 640 /dev/kmem c 1 2 
chown root.mem /dev/kmem 

port issimilar to mem, but the 10 ports are accessed. 

It is typically created by 

mknod -m 660 /dev/port c 1 4 
chown root.mem /dev/port 



FILES 

/dev/mem 

/dev/kmem 

/dev/port 

SEE ALSO 

mknod(l), chown(l), ioperm(2) 
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mouse— Serial mouse interface. 


CONFIG 

Serial mice are connected to a serial RS232/V 24 dialout line; see cua(4) for a description. 

DESCRIPTION 

The pinout of the usual 9 pin plug as used for serial mice is 


Pin 


Name 


Usd for 


2 

3 


RX Data 

TX -12V, lmax=10mA 

DTR +12 V, Imax = 10 mA 

RTS +12 V, Imax = 10 mA 

GND Ground 


This is the specification; in fact, 9 V suffices with most mice 

The mouse driver can recognize a mouse by dropping RTS to low. About 14ms later, the mouse will send 0x4D on the data 
line After a further 63ms, M icrosoft-compatible mice will send 0x33. Other mice send different values. 
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The relative mouse movement is sent asdx (positive means right) and dy (positive means down). Various mice can operate at 
different speeds. To select speeds, cycle through the speeds 9600,4800,2400, and 1200 bits/sec, each time writing the two 
characters from the table below and waiting 0.1 seconds The following table shows available speeds and the strings that 
select them: 

Bits'sec String 

9600 
4800 
2400 
1200 

Thefirst byteof a data packet can be used to synchronization purposes 

MICROSOFT PROTOCOL 

The M icrosoft protocol uses 1 start bit, 7 data bits, no parity, and 1 stop bit at the speed of 1200 bits/sec. D ata is sent to 
RxD in 3-byte packets The dx and dy movements are sent as two's-complement, ib(rb) issetwhen the left (right) button is 
pressed: 


Byte 

d6 

d5 

d4 

d3 

d2 

dl 

dO 

1 

1 

Ib 

rb 

dy7 

dy6 

dx7 

dx7 

2 

0 

dx5 

dx4 

dx3 

dx2 

dxl 

dxO 

3 

0 

dy5 

dy4 

dy3 

dy2 

dyl 

dyO 


Original M icrosoft mice have only two buttons However, there are some three-button mice that also use the M icrosoft 
protocol. Pressing the third button is reported by sending a packet with zero movement and no buttons pressed. 

M0USESYSTEMS PROTOCOL 

T he M ouseSystems protocol uses 1 start bit, 8 data bits, no parity, and 2 stop bits at the speed of 1200 bit^sec. D ata is sent 
to RxD in 5-byte packets dx is sent as the sum of the two two's-complement values dy is send as negated sum of the two 
two's-complement values ib (mb, rb) is cleared when the left (middle, right) button is pressed: 

Byte dl d6 d5 d4 d3 d2 dl dO 

1 1 ? ? ? ? lb mb rt> 

2 0 dxa6 dxa5 dxa4 dxa3 dxa2 dxal dxaO 

3 0 dxb6 dxb5 dxb4 dxb3 dxb2 dxbl dxbO 

4 0 dya6 dya5 dya4 dya3 dya2 dyal dyaO 

5 0 dyb6 dyb5 dyb4 dyb3 dyb2 dybl dybO 

SUN PROTOCOL 

The Sun protocol uses 1 start bit, 8 data bits, no parity, and 2 stop bits at the speed of 1200 bit^sec. Dataissentto RxD in 
3-byte packets, dx is sent as single two's-complement value, dy as negated two'scomplement value, ib (mb, rb) iscleared when 
the left (middle, right) button is pressed: 

Byte dl d6 d5 d4 d3 d2 dl dO 

1 1 ? ? ? ? Ib mb rt 

2 0 dx6 dx5 dx4 dx3 dx2 dxl dxO 

3 0 dy6 dy5 dy4 dy3 dy2 dyl dyO 


P 

*P 
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MM PROTOCOL 

TheM M protocol uses 1 start bit, 8 data bits, odd parity, and 1 stop bit at the speed of 1200 bits/sec. Data is sent to RxD in 
3-byte packets dx and dy are sent assinglesigned values, thesign bit indicating a negative value. ib(mb, rb) issetwhen the 
left (middle, right) button is pressed: 


Byte d7 d6 d5 d4 d3 d2 dl dO 


11? ? dxs 

dys 

lb 

mb 

rb 

2 0 dx6 dx5 dx4 

dx3 

dx2 

dxl 

dxO 

3 0 dy6 dy5 dy4 

FILES 

/dev/mouse a commonly used symlink pointing to a mouse device 

SEE ALSO 

cua(4), bm(4) 

dy3 

dy2 

dyl 

dyO 
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null, zero 

nun, zero— Data sink. 

DESCRIPTION 

D ata written on a nun or zero special file is discarded. 

Reads from the nun special file always return end of file, whereas readsfrom zero always return \0 characters. 

nun and zero are typically created by 

mknod -m 666 /dev/null c 1 3 

mknod -m 666 /dev/zero c 1 5 

chown root.mem /dev/null /dev/zero 

NOTES 

If these devices are not writable and readable for all users many programs will act strangely. 

FILES 

/dev/null 


SEE ALSO 

mknod(l), chown(l) 
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ram 


Ram disk device 



sd 


DESCRIPTION 

ram isa block device to access the ram disk in raw mode. 
It istypically created by 

mknod -m 660 /dev/ram b 1 1 
chown root.disk /dev/ram 

FILES 


SEE ALSO 

mknod(l), chown(l), mount(8) 
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sd 

sd- D river for SCSI disk drives. 

SYNOPSIS 

//include <linux/hdreg.h> 

CONFIG 

The block de/ice name has the following form: sdip, where 1 isa letter denoting the physical drive and p is a number 
denoting the partition on that physical drive. Often, the partition number, p, will be left off when the device corresponds to 
the whole drive. 

SCSI disks have a major de/ice number of 8 and a minor device number of the form (16 *drive_number) +partmon_number, 
where drive_number isthe number of the phys'cal drive in order of detection and partition_number isasfollows: 

Partition 0 The whole drive 

Partitions 1-4 The DOS "primary" partitions 

Partitions 5-8 The DOS "extended" (or "logical") partitions 

For example, /dev/sda will have major 8 and minor 0 and will refer to all thefirst SC SI drives in thesystem; /dev/sdb3 will 
have major 8 and minor 19 and will refer to the third DOS "primary" partition on thesecond SCSI drive in thesystem. 

At this time, only block devices are provided. Raw devices have not yet been implemented. 

DESCRIPTION 

Thefollowing ioctis are provided: 

hdio_req Returnsthe BIOS disk parameters in thefollowing structure: 

struct hd geometry { 
unsigned char heads; 
unsigned char sectors; 
unsigned short cylinders; 
unsigned long start; 


A pointer to this structure is passed astheiocti(2) parameter. 

The information returned in the parameter is the disk geometry of the 
drive as understood by D 0 SI Thisgeomdtry is not the physical geometry 
of the drive It is used when constructing the drive's partition table, 
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however, and is needed for convenient operation of fdisk(l), efdisk(l), 
and nio(l). If thegeometry information is not available zero is returned 
for all the parameters. 

blkgetsize Returns the device size in sectors Theiocti(2) parameter should be a 

pointer to along. 

blkrrpart Forces a re-read of the SC SI disk partition tables. N o parameter is 

needed. 

Thescsi(4) loctis are also supported. If the iocti(2) parameteris 
required and it is null, then iocti(2) will return -einval. 


FILES 

/dev/sd[a-h]: The whole device 

/dev/sd [ a - h ] [0-8]: Individual block partitions 


SEE ALSO 

scsi(4) 
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St 

st-SC SI tape device. 

SYNOPSIS 

#include <sys/mtio.h> 

int ioctl(int fd, int request [, (void *)arg3 ]) 
int ioctl(int fd, MTIOCTOP, (struct mtop *)mt_cmd) 
int ioctl(int fd, MTIOCGET, (struct mtget *)mt _s t at us) 
int ioctl(int fd, MTIOCPOS, (struct mtpos *)mt_pos) 

DESCRIPTION 

T he st driver provides the interface to a variety of SC SI tape devices. C urrently, the driver takes control of all detected 
devices of type sequential-access. T he st driver uses major device number 9. 

Each device uses two minor device numbers a principal minor device number, n, assigned sequentially in order of detection, 
and a no-rewind device number, (n +128). Devices opened using the principal device number are sent a rewind command 
when they are closed. Devices opened using the no-rewind device number are not. Options such asdensity or block size are 
not coded in the minor device number. These options must be si by explicit ioctiQ calls and remain in effect when the 
de/ice is closed and reopened. 

D evices are typically created by 

mknod -m 660 /dev/st0 c 9 0 
mknod -in 660 /dev/stl c 9 1 
mknod -m 660 /dev/nst0 c 9 128 
mknod -m 660 /dev/nstl c 9 129 

There is no corresponding block device. The character device provides buffering and read-ahead by default and supports 
reads and writes of arbitrary size (limited by the driver's internal buffer size, which defaults to 32768 bytes but can be 
changed either by using a kernel startup option or by changing a compile-time constant). 

D evice /dev/tape is usually created as a hard or soft link to the default tape device on the system. 
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ioctlS 

T he drive supportsthreeiocti requests Requests not recognized bythest drive are passed to the scsi drive. The 
definitions below are from /usr/inciude/iinux/mtio.h: 

mtioctop: PERFORM A TAPE OPERATION 

This request takes an argument of type (struct mtop *). Not all drives support all opeations. The drive returnsan EIO 
eror if the drive rqects an opeation. 

/* Structure for MTIOCTOP - mag tape op command: */ 
struct mtop { 

short mt_op; /* operations defined below */ 
int mt_count; /* how many of them */ 


Magnetic tape opeations 

MTBSF 

MTBSFM 

MTBSR 

MTBSS 

MTEOM 

MTERASE 

MTFSF 

MTFSFM 

MTFSR 

MTFSS 

MTNOP 

MTOFFL 

MTRESET 

MTRETEN 

MTREW 

MTSEEK 


MTSETBLK 

MTSETDENSITY 


MTWEOF 

MTWSM 


Backward spaceove mt_count filemarks. 

Backward space ove mt_count filemarks. Reposition the tape to the EOT 
side of the last filemark. 

Backward space ove mt_count records (tape blocks). 

Backward space ove mt_count setmarks. 

Go to the end of the recorded media (for appending files). 

Erase tape. 

Forward space ove mt_count filemarks 

Forward space ove mt_count filemarks Reposition the tape to the BOT 
side of the last filemark. 

Forward space ove mt_count records (tape blocks). 

Forward space ove mt_count setmarks. 

No op; flushes the drive's buffer as a side effet. Should be used before 
reading status with mtiocget. 

Rewind and put the drive off line. 

Reset drive 
Retention tape 
Rewind. 

Seek to the tape block numbe speified in mt_count. This opeation 
requires ei the a SC SI-2 drive that supports the locate command (device 
specific address) or aTandbeg-compatible SCSI-1 drive (Tandbeg, 
Archive Vipe, W angtek,...). The block numbe should be one that was 
previously returned by mtiocpos because the numbe isdevicespeific. 

Set the drive's block length to the value speified in mt_count. A block 
length of zeo sets the drive to veiable block size mode. 

Set the tape density to the codein mt_count. Some useful density 
codes are 

18 0X00 Implicit 0x11 QIC-525 

0x04 QIC-11 0x12 QIC-1350 

0x05 QIC-24 0x13 DDS 

0x0F QIC-120 0x14 Exabyte EXB-8200 

0x10 QIC-150 0x15 Exabyte EXB-8500 

W rite mt_count filemarks. 

W rite mt_count setmarks 
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MTSETDRVBUFFER 


MT_ST_BUFFER_WRITES 


MT_ST_ASYNC_WRITES 


MT_ST_RFAD_AHEAD 


MT_ST_TWO_FM 


MT_ST_DEBUGGI NG 
MT_ST_FAST_EOM 


Set various drive and driver options according to bits encoded in 
mt_count. T hese consist of the drive's buffering mode; six Boolean driver 
options, and the buffer write threshold. T hese parameters are initialized 
only when the device isfirst detected. T he settings persist when the device 
isdosed and reopened. A single operation can affect just the buffering 
mode just the Boolean options, or just the write threshold. 

A value having zeros in the high-order 4 bits will be used to set the drive's 
buffering mode. The buffering modes are: 

0 Thedrivewill notreportGOODStatusonwritecommandsuntil 

thedata blocks are actually written to the medium. 

1 The drive may report good status on write commands as soon 
as all thedata has been transferred to the drive's internal 
buffer. 

2 The drive may report good status on write commands as soon 
as all the data has been transferred to the drive's internal buffer 
and all buffered data from different initiators has been 
successfully written to the medium. 

To control the write threshold, the value in mt_count must include the 
constant mt_st_write_threshold logically 0 Red with a block count in the 
low 28 bits The block count refers to 1024-byte blocks, not the physical 
block size on thetape. The threshold cannot exceed the driver's internal 
buffer size (see the description). 

To set and clear the Boolean options the value in mt_count must include 
the constant mt_st_booleans logically 0 Red with whatever combination 
of thefollowing options is desired. Any options not specified are set false 
The Boolean options are 

(Default: true) Buffer all write operations. Ifthisoption isfalseand the 
drive uses a fixed block size then all write operations must be for a 
multiple of the block size This option must be set false to write reliable 
multi-volume archives 

(Default: true) When this options istrue, write operations return 
immediately without waiting forthedata to be transferred to the drive if 
the data fits into the driver's buffer. The write threshold determines how 
full the buffer must be before a new SCSI write command is issued. Any 
errors reported by thedrivewill beheld until the next operation. This 
option must be set false to write reliable multi-volume archives 
(D efault: true) T hisoption causes the driver to provide read buffering 
and read-ahead. Ifthisoption isfalseand thedriveusesafixed block size 
then all read operations must be for a multiple of the block size. 

(Default: false) This option modifies the driver behavior when afileis 
closed. The normal action isto writea single filemark. If the option is 
true thedriver will write two filemarksand backspaceover the 
second one 

Note that this option should not be sdt true for QIC tape drives because 
they are unable to overwrite a filemark. These drives detect the end of 
recorded data by testing for blank tape rather than two consecutive 
filemarks 

(D efault: false) Thisoption turnson various debugging messages from 
thedriver (effective only if thedriver was compiled with debug defined). 

(D efault: false) Thisoption causes the mteom operation to be sent directly 
to the drive potentially speeding up the operation but causing the driver 



to lose track of the current file number normally returned by the mtiocget 
request. If mt_st_fast_eom isfalse, thedriver will respond to an mteom 
request by forward spacing over files 
Example: 

struct mtop mt _cmd; 

mt _ c md. mt _ o p = MTSETDRVBUFFER; 

mt_cmd. mt.count =MT_ST_BOOLEANS | 

MT_ST_BUFFER_WRITES | 

MT_ST_ASYNC_WRITES; 
ioctl (f d, MTIOCTOP, & mt _ c md); 


MTIOCGET: GET STATUS 

This request takes an argument of type (struct mtget *)■ Thedriver returnsan EIO error if the drive rejects an operation. 
/* structure for MTIOCGET ■ mag tape get status command */ 
struct mtget { 

long mt_type; 

/* the following registers are device dependent */ 
long mt_dsreg; 
long mt_gstat; 
long mt_erreg; 

/* The next two fields are not always used */ 
daddr_t mt_fileno; 

daddr_t mt_blkno; 


T he header file defines many values for mt_type, but the current driver reports only the generic types mt_isscsii (G eneric 

SCSI-1 tape) and mt_isscsi 2 (Generic SCSI-2 tape). 

mt_resid is always zero. (Not implemented for SC SI tape drives) 

mt_dsreg reports the drive'scurrent settingsfor block size (in the low 24 bits) and density (in the high 8 bits). These fields are 

defined by mt_st_blksize_shift, mt_st_blksize_mask, mt_st_density_shift, and mt_st_density_mask. 

mt_gstat reports generic (device independent) status information. T he header file defines macros for testing these status bits: 


GMT_E0F(X) 


GMT_E0T(x) 

GMT_SM(x) 


GMT_E0D(x) 
GMT_WR_PROT(X) 


GMT_D_6250(x), GMT_D_1600(x), Gk 


GMT_DR_OPEN(x) 

GMT_IM_REP_EN(x) 


The tape is positioned just after a filemark (always false after an mtseek 
operation). 

T he tape is positioned at the begi nning of the first file (always false after 
an mtseek operation). 

A tape operation has reached the physical End of T ape 

The tape is currently positioned at asdtmark (always false after an mtseek 

operation). 

The tape is positioned at the end of recorded data. 

The drive is write-protected. Forsomedrivesthiscan also mean that the 
drive does not support writing on the current medium type. 

The last openo found thedrivewith atapein place and ready for 
operation. 

This generic status information reports the current density setting for 
9-track tape drives only. 

The drive does not have a tape in place. 

Immediate report mode (not supported). 
mt_erreg:The only field defined in mt_erreg isthe recovered error 
count in the low 16 bits (as defined by mt_st_softerr_shift and 
mt_st_softerr_mask). D ueto inconsistencies in the way drives report 
recovered errors, this count is often not maintained. 
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mt_fiieno reports the current file number (zero-based). This value isset to 
-i when the file number is unknown (such as after mtbss or mtseek). 
mt_bikno reports the block number (zero-based) within the current file. 
This value issdt to -i when the block number is unknown (such as after 

MTBSF, MTBSS, Or MTSEEK). 


MTIOCPOS: GET TAPE POSITION 

This request takes an argument of type (struct mtpos *) and reports the drive's notion of thecurrent tape block number, 
which isnotthesarneasmt_bikno returned by mtiocget. This drive must be a SCSI-2 drive that supports the read position 
command (device-specific address) oraTandberg-compatibleSCSI-1 drive (T andberg, Archive Viper, W angtek,...). 

/* structure for MTIOCPOS - mag tape get position command */ 
long mt_blkno; /* current block number */ 


RETURN VALUE 

EIO 

ENOSPC 

EACCES 

ENXIO 
EBUSY 
EOVERFLOW 

EINVAL 
ENOSYS 

COPYRIGHT 

Copyright 1995, Robert K. N ichols. 

Permission is granted to make and distribute verbatim copies of this manual, provided the copyright notice and this 
permission notice are preserved on all copies. Additional permissions are contained in the header of the source file 

SEE ALSO 

mt(l) 

Linux 1.1.86, 31 January 1995 


The requested operation could not be completed. 

A write operation could not be completed because the tape reached end- 
of-medium. 

An attempt was made to write or erase a write-protected tape. (This error 
is not detected during open().) 

D uring opening, the tape device does not exist. 

The device is already in useorthedriverwasunabletoallocatea buffer. 
An attempt was made to read or write a variable-length block that is 
larger than the driver's internal buffer. 

An loctio had an illegal argument, or a requested block size was i llegal. 
Unknown iocti(). 


tty 

tty— C ontrolling terminal. 

DESCRIPTION 

Thefile/dev/tty is a character file with major number 5 and minor number 0, usually of mode 0666 and owner.group 
root.tty. It is a synonym for the controlling terminal ofaprocess, if any. 

In addition to the loctio requestssupported by the device that tty refers to, the following loctio request is supported: 



vcs vcsa 


tiocnotty Detach the current process from its controlling terminal and remove it 

from its current process group, without attaching it to a new process 
group (that is, si its process group ID to zero). Thisioctio call only 
works on file descriptors connected to /dev/tty; this is used by daemon 
processes when they are invoked by a user at a terminal. The process 
attempts to open /dev/tty; if the open succeeds, it detaches itself from the 
terminal by using tiocnotty, but if the open fails, it isobviously not 
attached to a terminal and does not need to detach itself. 


FILES 

/dev/tty 

SEE ALSO 

mknod(l), chown(l), getty(l), termios(2), console(4), ttys(4) 


Linux, 21 January 1992 


ttys 

ttys— Serial terminal lines. 

DESCRIPTION 

ttyS[0-3] are character devices for the serial terminal lines 
T hey are typically created by 

mknod -m 660 /dev/ttyS0 c 4 64 # base address 0x03f8 

mknod -m 660 /dev/ttySI c 4 65 # base address 0x02f8 

mknod -m 660 /dev/ttyS2 c 4 66 # base address 0x03e8 

mknod -m 660 /dev/ttyS3 c 4 67 # base address 0x02e8 

chown root.tty /dev/ttyS[0-3] 

FILES 

/dev/ttyS[0- 3] 

SEE ALSO 

mknod(l), chown(l), getty(l), tty(4) 


Linux, 19 December 1992 


vcs, vcsa 

vcs, vcsa—Virtual console memory. 

DESCRIPTION 

/dev/vcs0 is a character de/ice with major number 7 and minor number 0, usually of mode 0644 and owner root. tty. 

It refers to the memory of the currently displayed virtual console terminal. 

/dev/vcs[i -63] are character devices for virtual console terminals; they have major number 7 and minor number 1 to 63, 
usually mode 0644 and owner root.tty. /dev/vcsa[0-63] are the same but include attributes and are prefixed with four bytes, 
giving the screen dimensionsand cursor position: lines, columns, x, y.(x =y =0 at the top-left corner of the screen.) 
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These replace the screendump ioctisof consoie(4), so the system administrator can control access using filesystem permis¬ 
sions. 

The devices for the first eight virtual consoles may be created by 

for x in 0 1 2345678; do 
mknod -m 644 /dev/vcs$x c 7 $x; 
mknod -m 644 /dev/vcsa$x c 7 $[$x+128]; 

chown root.tty /dev/vcs* 

N o iocti() requests are supported. 

EXAMPLES 

You can do a screendump on vt3 by switching to vtl and typing cat /dev/vcs3 >foo. 

This program displ ays the character and screen attri butes under the cursor of the second virtual console and then changes the 
background color there: 

#include <unistd.h> 

#include <stdio.h> 

#include <fcntl.h> 

{ int fd; 

struct {char lines, cols, x, y;} scrn; 


fd = open("/dev/vcsa2", 0_RDWR); 

(void)read(fd, Sscrn, 4); 

(void)lseek(fd, 4 + 2*(scrn.y*scrn.cols + scrn.x), 0); 
(void)read(fd, &ch, 1); 

(void)read(fd, Sattrib, 1); 

printf("ch= 1 %c' attrib=0x%02x\n", ch, attrib); 

(void)lseek(fd, -1, 1); 

(void)write(fd, &attrib, 1); 


FILES 

/dev/vcs[0-63] 

/dev/vcsa[0-63] 

AUTHOR 

Andries Brouwer (aeb@cwi.ni) 

HISTORY 

Introduced with version 1.1.92 of the Linux kernel. 

SEE ALSO 

console(4), tty(4), ttys(4), selection(l) 


Linux, 19 February 1995 




Part V: 


File Formats 







PartV: File Formats 



intro 

intro— Introduction to file formats. 

DESCRIPTION 

Thischapter describes various file formats and protocols, and the used C structures, if any. 

AUTHORS 

Look at the header of the manual page for the authors and copyright conditions Note that these can be different from page 
to page! 

Linux, 24July 1993 


active,active.times 

active, active .times— List of active U senet newsgroups. 

DESCRIPTION 

Thefile/news/iib/active lists the newsgroups that the local site receives. Each newsgroup should be listed only once. Each 
line specifies one group; their order in the file does not matter. Within each newsgroup, articles are assigned unique names 
which are monotonically increasing numbers 

If an article is posted to newsgroups not mentioned in this file, those newsgroups are ignored. If no valid newsgroups are 
specified, the article is filed into the newsgroup "junk" and only propagated to sites that receive the "junk" newsgroup. 

Each line consists of four fields specified by a space 

name hi mark I omark fl ags 

T he first field is the name of the newsgroup. N ewsgroups that start with the three characters to. are treated specially; see 
innd(8). The second field is the highest article number that has been used in that newsgroup. The third field is the lowest 
article number in the group; this number is not guaranteed to be accurate and should only betaken as a hint. Note that 
because of article cancellations, there may be gaps in the numbering sequence If the lowest article number is greater than the 
highest article number, there are no articles in the newsgroup. To make it possible to update an entry in-place without 
rewriting the entire file, the second and third fields are padded with leading zeros to make them afixed width. 

Thefourth field can contain one of the following flags: 
y Local postings are allowed 

n N o local postings are allowed, only remote ones 

m Thegroup ismoderated and all postings must be approved 

j Articles in thisgroup are not kept but only passed on 

x Articles cannot be posted to this newsgroup 

=f oo. bar Articlesare locally filed into thef oo. bar group 

If a newsgroup has the j flag, then no articles will be filed into that newsgroup and local postings to that group should not be 
generated. If an article for such a newsgroup is received from a remote site it will be filed into the "junk" newsgroup if it is 
not cross-posted. This is different from not having a newsgroup listed in the file because sites can subscribe to j newsgroups 
and the article will be propagated to them. 

If thefourth field of a newsgroup starts with an equal sign, then the newsgroup is an alias. Articles can be posted to thegroup 
but will be treated as if they were posted to the group named after the equal sign. T he second and third fields are ignored. 
Note that the newsgroup header is not modified (Alias groups are typically used during a transition and are typically created 
with ctiinnd(8)). An alias newsgroup should not point to another alias 
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Thefile/news/iib/active.times provides a chronological record of when newsgroups are created. Thisfile isnormally 
updated by innd(8) whenever a ctunnd newgroup command isdone. Each lineconsist of three fields: 


Thefirst field is the name of the newsgroup. The second field isthetimeit was created, expressed as the number of seconds 
since the epoch-a time_t; see gettimeofday(2).Thethird field istheelectronic mail address of the person who created the 
group. 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

ctlinnd(8), innd(8) 


adduser.conf 

adduser.conf—Configuration file for adduser(8) and addgroup(8). 

SYNOPSIS 

/etc/adduser.conf 


DESCRIPTION 

The file adduser.conf contains defaults for the programs adduser(8) and addgroup(8). Each option takes the form opt i on = 


The valid configuration options are 


DSHELL 

DHOME 

SKEL 

FIRSTJJID 


USERS_GID 


The login shell to be used for all new users. Defaults to /bin/bash. 

The directory in which new home directories should be created. Defaults to /home. 

The directory from which skeletal user configuration files should be copied. Defaults to / 

etc/skel. 

Specifies the lowest valid U ID for normal users on your system. I Dsbelow firstjjid are 
reserved for administrative and system accounts D efaults to 1000. 

TheusERGROUPS variablecan be either yes or no. If yes, each created user will be given their 
own group to use asa default, and their sdtup will arrangeto have them create files group- 
writable by default, thus allowing them to effectively use group-writeable filespace areas 
(such as /usr/iocai). If no, each created user will be placed in the group whose GID is 
users_gid, and they will create files not group-writeable by default. 

If usergroups is no, then users_gid istheGID given to all newly created users. The default 
value is 100. 


FILES 

/etc/adduser.conf 

SEE ALSO 

adduser(8) 


Debian GNU/Linux version 1.94 
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aliases 

aliases— Aliases file for sendmail. 

SYNOPSIS 

aliases 

DESCRIPTION 

Thisfile describes user ID aliases used by. Thefile resides in and isformatted asaseriesof lines of theform: 

name: name. 1, name.2, name.3, ... 

The name is the name to alias, and thename.n are the aliases for that name Lines beginning with whitespace are continuation 
lines. Lines beginning with # are comments. 

Aliasing occurs only on local names. Loops cannot occur because no message will be sent to any person more than once. 

After aliasing has been done, local and valid recipients who havea .forward filein their home directory have message 
forwarded to the list of users defined in that file. 

This is only the raw datafile; the actual aliasing information is placed into a binary format in the file and using the program 
newaiiases(l). A newaiiases command should be executed each time the aliase file is changed for the change to take effect. 

SEE ALSO 

newaiiases(l), dbm(3), sendmaii(8), "Sendmail Installation and Operation Guide" "Sendmail: An Internetwork M ail 
Route." 

BUGS 

Beause of restrictions in dbm(3), a single alias cannot contain more than about 1000 byte of information. You can get longe 
aliase by "chaining"— that is, making the last name in the alias a dummy name that is a continuation alias 

HISTORY 

The aliases file format appeared in BSD 4.0. 

BSD 4,10 May 1991 


cfingerd 

cfingerd— Configurable finge daemon. 

SYNOPSIS 

cfingerd [-c|-d|-e|-o|-v] 

-c Check configuration 

-d Run asdaemon, not inetd 

-e Emulate local finge without inetd 

-o Turn off all finge queie 

-v Request version information 

-c cheks your installed configuration. This make sure thee are no existing erore in the current cfingerd. conf file. 

-d runs cfingerd asa daemon. D on't run cfingerd this way if you're using inetd. 

-e allows you to emulate a local finge on a use that exists on your system. This make it so that you can test cfingerd on 
your system before installing it. U sing the -e directive isthesame as installing the software, typing finger user name® and 
getti ng the output. Using -e username doethesame. 
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-o turns off all finger queries. This makes it so that no one can finger your system- no matter what they try to do. 

-v requests cfingerd version information. 

DESCRIPTION 

cfingerd is a totally new and totally configurable finger daemon- one of the first. It utilizes the finger port (port 79) to 
provide useful information on each user on your system. H owever, cfingerd provides a unique twist, 
cfingerd was designed for the sole purpose of making output on finger queries configurable. I f you want to change any text 
that isdisplayed during finger queries, you can configure the finger daemon to display just about anything you want, 
cfingerd also takes into account any security breaches and attempts to close them. With .nofinger files, this isdisplayed 
instead of finger information, making it possible for users to keep themselves relatively anonymous from outside users 

WHY WAS IT DONE? 

The answer is simple: security. M any sites turn off finger for the reason that they don't want outside users to see who'son 
their system or get information about a specific user on their system. This seemed unfair to the rest of the users out there so 
this program was created. T hose sites were waiting for this type of program. M any sites that originally had their finger turned 
off turned them back on because of cfingerd. 

M any sites complained that they wanted the capability to create a fake user or a user that doesn't exist but calls a prewritten 
shell script, cfingerd takes this into account and provides the best method possible for creating such scripts (See 
cfingerd.conf(5) for more information on the configuration file) 

FEATURES Cfingerd PROVIDES AND DESCRIPTIONSOF each 

cfingerd was totally rewritten. W hy is this? T he older version of cfingerd had quite a few bugs, and it didn't quite do all the 
things that cfingerd now does This new version was totally revamped, and most of the bugs that were in the older version of 
cfingerd were removed in this one. The code is also more compact. 

H eader and footer displays were a big part of the original release of cfingerd and shall continue to remain in all versions. 
Headers and footers are only displays at the beginning and ending of all finger displays and are used as unique little 
advertisements 

The last time displayed is always a critical issue It's covered in cfingerd. cfingerd simply shows how many times this user is 
connected, what their idle time is on each tty they're connected to, and whether they are accepting messages. If they're not 
accepting messages, a [mesg-nj display will be shown. This display also shows the last time mail was read and whether this 
user has mail. 

Stand-alone and inetd support is compiled into the program, but only inetd support is given for the time being. The reason 
is that I have not yet added the option for stand-alone daemon mode 

.nofinger files are used when a user wants to remain anonymous. These files should be placed in their home directories and 
can display anything they want. There'sjust a few restrictions These .nofinger display files cannot be character devices 
directories, FIFOs soft or hard links or anything else of that caliber. They must only be normal files. 

F ake users were supported for the simple fact that many sites want to create users who don't exist and make them execute a 
shell. If you want this done install a fake user. Read cfingerd.conf(5) for more information on these useful options 
Service displays were used to show what fake users you have installed on your system. T hese can be formatted however you 
want and are explained in cfingerd.conf(5). 

Searching for usernames is a powerful feature that cfingerd takes full advantage of. If you are looking for a specific username 
on the system or don't know what their name is simply use the search, username directive with cfingerd, and you can search 
for a user on your system. 

Searching for usernames is not case sensitive. If you are searching for a specific username or part of the user's name, chances 
are that it'll be displayed. 



PartV: File Formats 


There's also an option to display your public PGP key if you have one. This is very useful if you want to keep your mail or 
other information secret to yourself and don't want "big brother" watching over your shoulder as you talk among yourselves. 
(Thanks to Andy Smith for this patch.) The standard plan file is. plan, project is. project, and PGP info is .pgpkey. 
Remember, any or all of these options stated can be turned on or off at will. If you want a specific option turned off, turn it 
off. 

ERROR MESSAGES 

Any error messages that result are fairly easy to debug if you know what to look for. 

Segmentation violations don't always occur, but if they ever do, you can pretty easily figure out what's going on. Unfortu¬ 
nately, cf ingerd doesn't have any compatibility with older cf ingerd. cont files, so if you get a segmentation violation, this 
means (usually) that your cf ingerd. cont file needs to be replaced. 

Time-outs usually mean that a script has timed out or a connection to another site timed out. 

SYSLOGGING MESSAGES 

There'sno real way to describe syslog messages because they can be changed as the system administrator chooses Although, 
examples can be given based on thestandard configuration that wasdistributed. 

If any IP addresses cannot be matched to a hostname SYSLOG will display ip: Hostname not matched. 

If the renice fails (to make the program run at the highest priority), then syslog will display Fatal - Nice died: (reason). 

If there is no buffer information iswaiting in the stdin buffer, syslog will display stdin contains no data. 

If a trusted host fingers your site, a <- Trusted will appear. 

If a reacted host fingers your site, a <- Rejected will appear. 

If root is fingered on your site, it will display Root. 

If a service listing was fingered on your site, syslog will display service listing. 

If a user listing was requested, syslog will display user listing. 

If a fake user was requested, syslog will display Fake user. 

If whois data was requested, syslog will display whois request. (Note that whois was not implemented in this release because 
it wasn't RFC compliant.) 

Any extra information pertaining to the incoming finger is displayed in the syslogging area. (It's also recommended that you 
reconfigure syslog.cont(5) to display to an unused VT.) 

BUGS 

W hen data isforwarded to other sites for fingering, it shows the output of the system that it forwarded thefinger request to. 
This has got to change. 

0 n ELF-specific systems, services lists usually show a bit of garbage at the beginning of thefinger display. This doesn't 
appear to beaproblem on a.out systems, so if you haveELF, you might want to compile cf ingerd asa.out if this becomes a 
problem. 

PLANS 

Any other optionsor improvements will probably come from user suggestions 

Later plans will mean you can define your own display formats for the finger display. This means that you can redefine how 
you want your finger display to look. 

CONTACTING 

If you like the software and you want to learn more about it or want to see a feature added to it that isn't already here, write 

to khollis@bltgate.com. 
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I've received calls at work pertaining to the software, and although I appreciate the fact that people like the software I wrote, 
I'd appreciate it if you leave me e- mail and be considerate. 

cfingerd isnow being maintained by M ichael Jarvis. Any additions after cfingerd 1.2.3 should be directed toward M ichael. 
YOU Can reach him at mjarvis@qns.com. 

If you want to see other projects that Bitgate Software is currently developing, check out the W eb page at http: / / 
www.bitgate.com/. This will contain all the update information on the software that is being developed and that is already 
released. 


SEE ALSO 

cfingerd.conf(5), finger(l), userlist(l), syslog.conf(5) 


cfingerd 1.2.3, 24 May 1996 


cfingerd.conf 

cfingerd.conf— Configurable finger daemon configuration file. 

SYNOPSIS 

/etc/cfingerd.conf 

DESCRIPTION 

cfingerd.conf is the configuration filefor cfingerd. This has been totally rewritten to support a more readable configuration 
file. This version of the new configuration file is not compatible with the older versionsfrom 1.0.3 or earlier. 

Each line in the configuration file is split into three sections files, config, and hosts. Each one of those sections is split into 
subsections 

Subtext of each option is either Boolean options, string options or switchable options, all changeable by the system 
administrator. 

Each section is split into a series of sections that resembles C-type definition; it’s not exact but close enough to be familiar. 
There's only one exception: These are not case sensitive. Any casing will do as long as the option is legal. 

Thus, each option isformatted like this: 

OPTION sub_option_name = { 

(tab/space) string_option = "string format", 

(tab/space) boolean_option = [BOOL, BOOL], 

(tab/space) +/-internal_config_option 
(tab/space) host.name.here 
} 

This shows that string options are strings put into quotes, Boolean options are given as true and false, switchable options 
are given with the + or - directive and hostnames are used as substrings so that wildcards are not necessary. 

You can add comments using the hash mark(#) at the beginning of theline. Please note that no commentsare allowed inside 
of an option. 

DISPLAY FILES SECTION (FILES display files) 

Each option here is a string option. These are formatted asthe example shows 

plan is the plan file that is used when displaying a plan. The standard here is. plan. 

project isthe project file that is used when displaying a project description. The standard here is .project. 

pgp_key isthe Pretty-Good-Privacy file that is shown when displaying a public or private key. The standard here is .pgpkey. 
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(The preceding three files must be world readable but should not be world writable. This makes sure that ctingerd can read 

the file once it becomes the "nobody" UID/GID. This is generally a good idea for protection.) 

no_finger is the file that is shown when a user wants to remain anonymous. This is usually the case with root users (which 

should be standard anyway). The standard here is .nofinger. This file can only be a standard displayablefile 

logfile isthefilethat is used to keep logs of everything that happens to both your system and the finger program. These logs 

are kept as backups for your finger file and can be used to guard against attacks against your system if a finger attack occurs 

Remember, the ctingerd.conf file is root owned, so thisfile should be kept in a safe hidden place. 

header_display isthefilethat isdisplayed at the top of each finger display. Thestandard hereis/etc/ctingerd/ 

top_finger.txt. 

footer_display isthefilethat isdisplayed at the end of each finger display. Thestandard hereis/etc/ctingerd/ 
bottom_finger.txt. 

no_user_banner isthefilethat isdisplayed if the user doesn't exist. Thestandard hereis/etc/cfingerd/nouser_banner.txt. 
no_name_banner isthefilethat isdisplayed if no name was specified in a finger display. This is used in conjunction with the 
system_list option (explained later). Thestandard hereis/etc/ctingerd/noname_banner.txt. 

rejected_banner isthefilethat isdisplayed if a rqected host tries to finger your system for any reason. The standard here is/ 
etc/cfingerd/rejected_banner.txt. 

FINGER DISPLAY CONFIGURE SECTION (CONFIG finger display) 

Each option in this section is Boolean. The way this works is as follows Thefirst Boolean option is the setting for a remote 
host or a host that fingers you from the outside. The second Boolean option is the setting for the local host or trusted host. 
This is what people from your own system will see. 

Each option hasa- or + option. Thisisfor user-overridable options, which will be in the next release of ctingerd. These will 

allow users to manipulate if this information isdisplayed when that specific user isfingered. 

header_file displays the header file at the beginning of each finger query. 

footer_file displays the footer file at the end of each finger query. 

login_id displays the login ID of that particular user. 

real_name displays the real name of that particular user. 

directory displays the user's directory. 

shell displays the user's shell. 

room_number displays the user's room number. 

work_number displays the user's work phone number. 

home_number displays the user's home phone number. 

other displays the user'sother information. 

last_time_on displays the last time the user logged into the fingered system. 
if_online displays whether the user is currently logged into thefingered system. 
time_mail_read displays the last time that the fingered user read mail. 
day_mail_read displays the last day that thefingered user read hisor her mail. 
origination displays the site from which the user logged in (if applicable). 
plan displays the user's plan file. 
project displays the user's project file. 
pgp displays the user's Pretty-G ood-Privacy key file. 
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no_name_banner displays the banner if no username was given. 

rejected_banner displays the rqected banner if the site fingering your system was in the banned-site listing. 
system_list displays the system list if one was requested. 
no_name displays the no-name display file if no user was selected. 

INTERNAL CONFIG CONFIGURE SECTION (CONFIG internal config) 

Each item in this section isaswitchableoption.Thismeansthata +before the item isturned on and a - before the item is 
turned off. 

allow_multiple_finger_display allows you to give a sorted output of all users on more than one specific system. This is useful 
when you have more than oneISP machine located in different citiesoreven states 

allow_searchable_finger allowsyou to let others outside your system (or within it) to search for a specific username by using 
the search. username directive. 

al low_no_i p_m atch_f i nge r allowsyou to Idt sites finger your system if a hostname could not be matched to their IP address 
successfully. 

allow_user_override will allow your users to override specific optionsin the finger display section that you enable. 
allow_userlist_only will allow other sites that are fingering your system for a specific compiled user list to finger your system 
and get a user listing of who's online This could be a security risk, so you might want to turn this option off if you feel it's a 
security risk. 

allow_finger_forwarding will allow other sitesto forward finger requests to a different machine if the user could not be 
located on the current machine. (In order to use this option, you must have the hosts finger forward option sdt and have 
other sites in there.) 

allow_strict_formatting makes the finger display remove all returns between display options This makes the finger display 
look horrible(aswith GNU Finger or the other generic fingers) and makes your system look, well, "generic." 
allow_verbose_timestamping makes the timestamp that is displayed (at any place) very verbose. For instance where it used to 
say 

On since Sat Aug 12 03:43PM(PDT) 

would now be shown as 

On since Sat Aug 12, 1995 03:43PM(PDT) 

(Basically, allow_verbose_timestamping just takesup more room on the display field.) 

allow_nonident_access lets you only allow connectionsfrom sites that run theident daemon (or RFC 1413-compliant 
program.) Thisisfor security sake and is a good measure against unknown users trying to finger your system. If this option i< 
enabled, users who do not haveidentd running on their system (such as Windows users) will be able to finger your system. 
Systems not running identd will return unknown as the user ID and will not be permitted to finger a user on your system. 
allow_finger_logging enables cfingerd to usethe logfile file to store any logs of activity that happen to your system via 
finger. 

allow_line_parsing makes cfingerd parse each line of every display file (including the plan, project, and pgp files) for any 
efingerd-specifics commands. If any are found, cfingerd will parse these commands and display correct information 
accordingly. Otherwise, if this isturned off, the display will appear without parsed commands 

allow_execution will allow usersto execute scripts in place of their .plan, .project, and .pgp files. Thisisused to display the 
standard output of another program directly to the screen of the user. Keep in mind that this is a huge security risk if you 
choose to use it. It’s normally suggested that this option remain off, but you can turn it on if necessary. N evertheless, these 
programs are called as nobody .nogroup. 
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allow_fakeuser_finger turnson or off the fake user option in cfingerd. If you want fake users to be defined and available to 
be fingered, you will want to enable this option. This can be a security risk in some instances if you allow for searchable 
fingers and your script calls an execute routine on that variable. Chances are that'll never happen. 
allow_userlog will allow usersto keep track of who has fingered them and at what time A little file cal led .fingeriog will 
appear in their directory, which they can examine to see who has fingered them. If you don't care about this, you can disable 
it. Otherwise it’s not a bad idea. (It also logs root fingers as well.) 

SYSTEM LIST SITES CON FIGURE SECTION (CONFIG system list sites) 

This isjust a series of hostnames that you want to finger when displaying your user-list display. If you have more than one 
system that you want to show, simply put their hostname in this list, separated on a line by itself. 

For example, if I have a separate ISP system that I’m running on the side saychatiink.com, I would change my configuration 
to say 

CONFIG system_list_sites = { chatlink.com, local host } 

Remember, if you are listing only a couple of sites, list the sites you will want to have listed (in order) first. The ending entry 
must be i oca i host or thefinger listing will not include your site If you include local host anywhere else in the list, it will 
stop once it has reached thei ocai host entry, so remember to list it last I 

I want to get a user listing from my own machine and from chatunk. corn's system. This would be automatically formatted 
nicely (sorted and parsed) and would display on thescreen in sorted order. This program is usually used in tandem with the 
supplied useriist(l) program. 

If no system list sites are specified, multiple system sites will not be specified. 

TRUSTED HOST SECTION (HOSTS trusted) 

T his is a listing of the sites that you allow to finger your system exclusively, giving them the same access that your local users 
would get. I n other words, they are treated as i o c a i host users 

Each site that you list in this section should be separated by using the, directive. You can include up to 80 sites in this 
listing. 

Wildcards are supported in this section, and you can use them in the regex format as well. Any wildcards with *, ?, or any 
other regex wildcard matching character will work. IP addresses will also work. H ostnames are compared case insensitive. 

REJECTED HOST SECTION (HOSTS rejected) 

This is a listing of the sites that you do not allow to finger your system. These sites don't get to finger anyone (or anything 
for that matter) on your system, regardless of what they try to do. In essence finger is cut off to that particular system. 

Each site that you list in this section should be separated by using the, directive. You can include up to 80 sites in this 
listing. 

Wildcards are supported in this section, and you can use them in the regex format as well. Any wildcards with *, ?, or any 
other regex wildcard matching character will work. IP addresses will also work. H ostnames are compared case insensitive. 

FORWARDED HOST SECTION (HOSTS finger forward) 

T his is a listing of sites that are used to forward a finger query to when a finger request was processed but that particular user 

was not found on the associated system. It will step through this listing, and it will search for the user in question. If the user 

could not be found, then it will step through to the next host and the next, until it finds one 

Each site that you list in this section should be separated by using the, directive. You can include up to 80 sites in this 

listing. 

Wildcards are supported in this section, and you can use them in the regex format as well. Any wildcards with *, ?, or any 

other regex wildcard matching character will work. H ostnames are compared case insensitive 

If you do not specify any forwarding sites in this section, finger forwarding will be disabled for your system. 
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FINGER STRING SCON FIGURE SECTION (CONFIG finger strings) 

Each option in this section isa string that can be changed to fit your needs when displaying finger information. These strings 

are limited to about 20 characters on the display. (If you use more than 20, thefinger display will end up looking strange) 

user_name isthe string that isdisplayed when the user's username isshown. 

real_name isthe string that is displayed when the user's real name is shown. 

directory isthe string that isdisplayed when the user's directory isshown. 

shell isthe string that isdisplayed when the user's shell isshown. 

room_number isthe string that is displayed when the user's room number isshown. 

work_number isthe string that is displayed when the user's work phone number isshown. 

home_number isthe string that is displayed when the user's home phone number isshown. 

other is the string that isdisplayed when the user's other display information is show. 

plan isthe string that isdisplayed when the user's plan isshown. 

project isthe string that isdisplayed when the user's project isshown. 

pgpkey isthe string that isdisplayed when theuser's PG P key isshown. 

no_plan isthestring that isdisplayed when the user doesn't havea plan file to show you. 

no_project isthe string that isdisplayed when the user doesn't havea project file to show you. 

no_pgp isthestring that isdisplayed when the user doesn't havea PGP key file to show you. 

wait isthestring that isshown when the system gathers information from other sitesfor a user listing. 

INTERNAL STRING SCON FIGURE SECTION (CONFIG internal strings) 

These strings are changeable and can beany length you want (within reason). These strings are concatenated into the 

syslogging display when the appropriate finger has been issued. This section also includes error messages that may occur. 

no_ip_host isshown when there is no hostname that matches the incoming IP address. This usually indicates that either the 

site didn't register its IP address with the I nterN 1C or it is coming from a hacked site. 

renice_fatal isshown when the system failed to change the execution priority on the current process of cfingerd. 

stdin_empty isshown when the input buffer on the cfingerd port is empty. (This should never really happen; it's here for 

sanity.) 

trusted_host isshown when atrusted host fingers your system. If you do not specify a trusted host, cfingerd will insert 
i ocai host into thisfield. 

rejected_host isshown when a rejected host fingers your system. If you do not specify a rejected host, cfingerd will insert 
0.0.0.0 into thisfield. 

root_finger isshown when a user fingers root. 

service_finger isshown when a user requestsfake user services from your system. 
user_list isshown when a user requests a user listing from your system. 
fakejjser isshown when a user fingers a fake user from your system. 

whoisjjser isshown when a user fingers a user with aWHOISquery. (This option is not yet available.) 
finger_deny isshown when a user tries to finger with aforward request such asuser ©host l ©host 2. T his isnot supported 
because it could result in finger loops and a lot of traffic. 

SIGNAL STRING SCON FIGURE SECTION (CONFIG signal strings) 

Thissection isused in changing the output that is given when asystem crashes, or a signal iscaught, and reported to the 
finger output. 
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The supported caught signals are as follows 

SIGHUP, SIGINT, SIGQUIT, SIGILL, SIGTRAP, SIGABRT, SIGFPE, SIGUSR1, SIGSEGV, SIGUSR2, SIGPIPE, SIGALRM, SIGTERM, SIGCONT, 
SIGTSTP, SIGTTIN, SIGTTOU, SIGIO, SIGXCPU, SIGXFSZ, SIGVTALRM, SIGPROF, SIGWINCH 

FINGER PROGRAMSFILESSECTION (FILES finger programs) 

These are the programsthat are called when a specific action istakeon the finger display. 

finger isthe file that is used when a user listing isrequested from your machine This is used in thestandard user list and in 

the sorted user list, so it is wise to use the standard here: /usr/sbin/useriist. 

who is isthe program that is used when a W H 01S request isdoneon a specific user. 

FINGER FAKE USERS FILES SECTION (FILES finger fakeusers) 

T hese are the ever- popular fake users that you can create on your system. T hese users are ones that don't exist (and should 
not exist, for that matter). T hese are instead, treated as normal scripts that can be called for your use 
Theformat is asfollowsfor fake users: 

fake_username Seri p t _ n a me SEARCHBOOL scri pt 

fake_username is the name of the fake user you want to request. M ake sure that this is a user that does not exist on your 

system. Keep in mind that if you create a fake username and that user already exists, the fake username will be shown. 

s c r i pt. n a me is the standard name of your script. T his is used in the display of your services listing. 

searchbool specifies whether parameters can be sent to that specific fake user. If you decide to use the searchbool option 

(true in thiscase), the passed variables are 

$1 First passed option 

$2 Second passed option 

$3 Third passed option 

$4 Fourth passed option 

(If more than four options were passed to this, the request will be ignored, and an error message will be returned to the user 
who requested thefinger request.) 

scri pt isthe location of your script. It should bechmod 700 and readable only by root. 

If you do not specify any fake users, a fake user called None will be created. This isa fake user that does nothing and calls / 
dev/nuii for the script. 

SERVICES HEADER CONFIGURE SECTION (CONFIG services header) 

This is the display that is given during a services finger. It should be formatted the same way that you want it to display on 
the screen. 

When specifying thefinger formatted options, you should specify them asC formatted strings as well, with thestandard 
options This should always be given last in the display. 

An example of this is 

Welcome to this system's services! 

User: Service name: Searchable: 

%-8s %-20s %-s 

Remember to keep theformat string last or a sigsegv will result. 

SERVICESPOSITIONSCONFIGURE SECTION (CONFIG services positions) 

This specifies where in the preceding display string that the information from a service listing isto appear. These numbers 
can be anywhere between 1 and 3. 
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user specifies the position of the username listing. 
service specifies the position of the service full-name listing. 
search specifies the position of the Boolean search display. 

CONTACTING 

If you like this program and have questionsor comments about the program's functionality or what-have- you, write to 

khollis@bitgate.com. 

As always, I appreciate any suggestions or bug reports you might have, so bring them on! 


SEE ALSO 

cfingerd(8), cfingerd.text(5), userlist(l), finger(l), regex(3), regexp(3) 


16 May 1996 


cfingerd text ru I es 

EXPLANATION 

cfingerd offers different commands that can be placed in text files to display corresponding information. Each command 
used with cfingerd in text files begins with a dollar sign ($). This usually indicates to cfingerd that when it's displaying a file 
it parses the command directly after that character. 

If you want to display a raw $ sign, simply put two $ signs together, or $$. 

TEXT COMMANDS 

Thefollowing is a list of text commands and what they do. Each of the text commands can be in any text case; it doesn't 
matter. 

$CENTER 

$DATE 
$TIME 
$IDENT 

$COMPILE_DATETIME 

$VERSION 
$EXEC 

SEE ALSO 

cfingerd(8), cfingerd.conf(5), finger(l), useriist(l), any of the included docswith the standard cfingerd distribution. 

cfingerd 1.2.1, 6 ]an 1996 


D i splays the entire contents of the line. This command must start at the beginning of the 
line Thisisa very common command. 

D i splays the current system date in theformat of M M ID D/YY. 

Displays the current system timein theformatH H :M M A/PM (timezone). 

D isplaysthe identity of thecurrent person fingering your system. 

Displays the date and time of which thecurrent issue of cfingerd was compiled on your 
system. 

D isplaysthe current version of cfingerd. 

Executes a file with * parameters after it. The$EXEC command must be on a line by itself 
in order to function properly. The command is executed as nobody, nogroup. 


control.ctl 

controi.cti- Specify handling of Usenet control messages. 
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DESCRIPTION 

Thefile/news/iib/controi.cti isused to determine what action is taken when a control message is received. It is read by the 
parsecontroi script, which iscalled by all thecontrol scripts (For an explanation of how the control scripts are invoked, see 
innd(8).) 

Thefile consistsof a series of lines; blank lines and lines beginning with a number sign (#) areignored. All other lines consist 
of four fields separated by a colon: 

Thefirst field is the name of the message for which thisline is valid. 11 should be either the name of thecontrol message, or 
the word an to mean that it is valid for all messages. 

The second field is a shell-style pattern that matches the e-mail address of the person posting the message. (The poster's 
addressisfirst converted to lowercase.) The matching isdone using the shell'scase statement; see sh(l) for details. 

If thecontrol message is newgroup or rmgroup, then the third field specifies the shell-style pattern that must match the group 
being created or removed. If thecontrol message is of a different type, then this field is ignored. 

Thefourth field specifies what action to take if this line is selected for the message Thefollowing actions are understood: 
doit Theaction requested by thecontrol messageshould be performed. In most cases, thecontrol script 

will also send mail to Usenet. 

doifarg If the control message has an argument, this is treated as a doit action. If no argument was given, it 

is treated as a mail entry. This is used in asendsys entries script so that a site can request itsown 
newsfeeds(5) entry by posting asendsys mysite article 0 n the other hand, sendsys bombs ask that 
the newsfeeds file be sent; if you use doifarg, such messages will not be processed automatically. 
doit=f i i e Theaction is performed, but a log entry is written to the specified log file, fi e. If f i i e is the word 

mail, then the record is mailed. A null string is equivalent to /dev/nuii. A pathname that starts with 
a slash istaken as the absolute filename to use as the log. All other pathnames are written to /var/ 
log/news/file. log. The log is written by writelog (see newslog(8)). 
drop No action istaken; the message is ignored. 

log A one-line log notice is sent to standard error, innd normally directs thisto thefile /var/iog/news/ 

errlog. 

iog=f i i e A log entry is written to the specified log file, file, which is interpreted as described previously, 

mail A mail messageissenttothenewsadministrator. 

Lines are matched in order; the last match found in thefileistheonethatisused. For example, with thefollowing three 
lines: 



A newgroup coming from tale at aUUN ET machine will be honored if it is in the mainstream Usenet hierarchy. If kre 
posts a newgroup message creating aus.foo, then man will be sent. All other newgroup messages are ignored. 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

innd(8), newsfeeds(5), scanlogs(8) 

CVS 

cvs— C oncurrent Versions System support files 
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SYNOPSIS 

$CVSROOT / CVSROOT/commit inf o,v 
$CVSROOT/CVSROOT/cvsignore, v 
$CVSROOT/CVSROOT/cvswrappe rs, v 
$CVSROOT/CVSROOT/editinfo, v 
$CVSROOT/CVSROOT/history 
$CVSROOT/CVSROOT/loginfo, v 
$CVSROOT/CVSROOT/modules, v 
$CVSROOT/CVSROOT/rcsinfo,v 
$CVSROOT/CVSROOT/taginfo, v 

DESCRIPTION 

cvs isasystemfor providing source control to hierarchical collections of source directories Commands and procedures for 
using cvs are described in cvs(l). cvs manages source repositories, the directories containing master copies of the revision- 
controlled files by copying particular revisions of the files to (and modifications back from) developers' private working 
directories. In terms of file structure, each individual source repository is an immediate subdirectory of $cvsroot. The files 
described here are supporting files they do not have to exist for cvs to operate, but they allow you to make cvs operation 
more flexible 

You can use the modules file to define symbolic names for collections of source maintained with cvs. If there is no modules 
file, developers must specify complete pathnames (absolute or relative to scvsroot) for the files they want to manage with cvs 
commands You can use the commiunfo file to define programs to execute whenever cvs commit isabout to execute. These 
programs are used for "precommit" checking to verify that the modified, added, and removed files are really ready to be 
committed. Some uses for this check might be to turn off a portion (or all) of the source repository from a particular person 
or group or perhaps to verify that the changed fi les conform to the site's standards for coding practice 
You can usethecvswrappers file to record cvs wrapper commands to be used when checking files into and out of the 
repository. W rappers allow the file or directory to be processed on the way in and out of cvs. The intended uses are many; 
onepossibleuseisto reformat a C file before thefile ischecked in so all the code in the repository looks the same. You can 
use the loginfo file to define programs to execute after any commit, which writes a log entry for changes in the repository. 
These logging programs might be used to append the log message to a file or send the log message through electronic mail to 
a group of developers. You can also post the log message to a particular newsgroup. 

You can use the taginfo file to define programsto execute after any tag or rtag operation. These programs might be used to 
append a message to a file listing the new tag name and the programmer who created it, to send mail to a group of develop¬ 
ers, or to post a message to a particular newsgroup. You can use the ncsinfo file to define forms for log messages You can use 
the editinf o fileto define a program to execute for editing or validating cvs commit log entries. This is most useful when used 
with a rcsinfo forms specification because it can verify that the proper fields of the form were filled in by the user commit¬ 
ting the change. You can usethecvsignore fileto specify the default list of files to ignore during update. You can use the 
history fileto record the cvs commands that affect the repository. The creation of thisfile enables history logging. 

FILES 

modules The modules file recordsyour definitions of namesfor collections of sourcecode. 

cvs will use these definitions if you use cvs to check in a file with the right 
format to $cvsR00T/cvsR00T/moduies,v. The modules file can contain blank lines 
and comments (lines beginning with #) as well as module definitions. Long lines 
can be continued on the next line by specifying a backslash (\) as the last 
character on the line A module definition is a si ngle I ine of the modules file in 
either of two formats. In both cases, mname represents the symbolic module name 
and the remainder of the line is its definition. 

This represents the simplest way of defining a module mn a me. T he -a flags the 
definition as a simple alias: cvs will treat any use of mname (as a command 
argument) as if the list of names a i i as es had been specified instead, ai i ases may 
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contain either other module names or paths When you use paths in a i i ases.cvs 
checkout creates all intermediate directories in the working directory, just as if the 
path had been specified explicitly in thecvs arguments 
mname [ options ] dir [files ... ] [&modul e ...] 

In thesimplest case, thisform of module definition reduces to mname dir. This 
defines all the files in directory di r as module mname di r is a relative path (from 
$cvsroot ) to a directory of source in oneof the source repositories In this case 
on checkout, a single directory called mname iscreated as a working directory; no 
intermediate directory levels are used by default, even if di r was a path involving 
several directory levels By explicitly specifying files in the module definition after 
dir, you can select particular files from directory di r .The sample definition for 
modules is an example of a module defined with a single file from a particular 
directory. H ere is another example: 

m4test unsupported/gnu/m4 foreach.m4 forloop.m4 

With this definition, executing cvs checkout m4test will create a single working 
directory m4test containing the two files listed, which both come from a 
common directory several levels deep in the cvs source repository. A module 
definition can refer to other modules by including &mo d u i e in its definition. T he 
checkout command creates a subdirectory for each such module in your working 
directory. New in cvs 1.3; avoid thisfeature if sharing module definitions with 
older versions of cvs. 

Finally, you can useoneor moreof thefollowing options in module definitions 
-d name namestheworking directory something other than the module name. 
This option is new in cvs 1.3; avoid thisfeature if sharing module definitions 
with older versions of cvs. -t prog allowsyou to specify a program prog to run 
whenever files in a module are committed, prog runs with a single argument, the 
full pathname of the affected directory in a source repository. The commitinfo, 
loginfo, and editinto files provide other ways to call a program on commit, -o 
prog allowsyou to specify a program prog to run whenever filesin a module are 
checked out. prog runs with a single argument, the module name, -e prog allows 
you to specify a program prog to run whenever files in a module are exported, 
prog runs with a single argument, the module name, -t prog allowsyou to 
specify a program prog to run whenever files in a module are tagged, prog runs 
with two arguments the module name and the symbolic tag specified to rtag. -u 
prog allowsyou to specify a program prog to run whenever cvs update isexecuted 
from the top-level directory of the checked-out module, prog runs with a single 
argument, the full path to the source repository for this module, 
commitinfo, loginfo, rcsinfo, editinfo These files all specify programs to call at different points in the cvs commit 

process They have a common structure. Each line is a pair of fields a regular 
expression, separated by whitespace from a filenameor command-line template. 

W henever oneof the regular expression matches a directory name in the 
repository, the rest of the line is used. If the line begins with a# character, the 
entire line is considered a comment and is ignored. Whitespace between the 
fields is also ignored. For loginfo, the rest of the line is a command-line template 
to execute. T he templates can include not only a program name but also 
whatever list of arguments you want. If you write %s somewhere on the argument 
list, cvs supplies, at that point, the list of files affected by the commit. The first 
entry in the list isthe relative path within the source repository where the change 
is being made. The remaining arguments list the files that are being modified, 
added, or removed by this commit invocation. For taginfo, the rest of the line is 
acommand-linetemplateto execute The arguments passed to the command are, 
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in order, thetagname, operati on (add for tag, mov for tag -F, and del for tag -d), 
and repository, and any remaining are pairs of filename revision. A nonzero exit 
of the filter program will cause the tag to be aborted. Forcommitinfo, the rest of 
the line is a command-line template to execute The template can include not 
only a program name but also whatever list of arguments you want. The full path 
to the current source repository is appended to the template, followed by the 
filenames of any files involved in the commit (added, removed, and modified 
files). For rcsinfo, the rest of the line isthefull path to a file that should be 
loaded into the log message template. For editing, the rest of the line isa 
command-line template to execute The template can include not only a 
program name but also whatever list of arguments you want. T hefull path to the 
current log message template file is appended to the template. You can use one of 
two special strings instead of a regular expression: all specifiesa command-line 
tempi ate that must always be executed, and default specifiesa command-line 
template to use if no regular expression isa match. The commitinfo file contains 
commands to execute before any other commit activity, to allow you to check 
any conditions that must be satisfied before commit can proceed. The rest of the 
commit will execute only if all selected commands from thisfile exit with exit 
status 0. T he rcsinfo file allows you to specify log templates for the commit 
logging session; you can use this to provide a form to edit when filling out the 
commit log. Thefield after the regular expression, in thisfile, containsfilenames 
(of files containing the logging forms) rather than command templates The 
editinfo file allows you to execute a script before the commit starts but after the 
log information is recorded. These "edit" scripts can verify information recorded 
in the log file If the edit script exits with a nonzero exit status thecommit is 
aborted. Theioginfo filecontainscommandsto execute at the end of acommit. 
The text specified as a commit log message is piped through the command; 
typical uses include sending mail, filing an article in a newsgroup, or appending 
to a central file. 

cvsignore, .cvsignore Thedefault list of files (or sh(l) filename patterns) to ignoreduring cvs update. 

At startup time cvs loads the compiled default list of filename patterns (see 
cvs(l)). Then the per-repository list included in $cvsR00T/cvsR00T/cvsignore is 
loaded, if it exists. 

Then the per-user list is loaded from $home/. cvsignore. Finally, ascvs traverses 
through your directories, it will load any per-directory .cvsignore files whenever 
it finds one T hese per-directory files are only valid for exactly the directory that 
containsthem, not for any subdirectories. 

history C reate thisfile in scvsroot/cvsroot to enable history logging (see the description 

Of cvs history). 

SEE ALSO 

CvS(l) 

COPYING 

Copyright® 1992, Cygnus Support, Brian Berliner, and Jeff Polk. 

Permission is granted to make and distribute verbatim copies of this manual, provided the copyright notice and this 

permission notice are preserved on all copies. 

Permission isgranted to copy and distribute modified versions of this manual under the conditionsfor verbatim copying, 

provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 
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Permission isgranted to copy and distribute translations of this manual into another language under the preceding 
conditions for modified versions, except that this permission notice may be included in translations approved by the Free 
Software Foundation instead of in theoriginal English. 

12 February 1992 


DEVINFO 

devinfo— Device entry database. 

DESCRIPTION 

devinfo is a text fi le that describes all the possible devices for a system. 11 is used by makedev(8) to create special file entries in / 
dev. It may be named either /dev/DEviNFO or /etc/devinto. Information about custom local devices, if any, should be placed 
in devinfo. local or /etc/devinto. local, which has the same syntax. 

T hefile format is free-form. C, C++, and shell comments are understood. There are basically four statements: 
ignore { proc-devi ce... } T his causes the specified names to be ignored if found in /proc/devices. 
batch { device... } Thiscreates a "batch"- a collection of devices that will all becreated when the batch is 

invoked. For example, in the standard devinfo, "generic" isa batch, 
block device-spec T his defines one or more block devices, 

char device-spec T his defines one or more character devices. 

H ere i sasampi e devi ce-spec: 

(std, 1) < 
mem (kmem) : 1 
null (public) : 3 
core -> "/proc/kcore" 


This example defines a group of devices called std, with major number 1. Running will create all the devices in the group; 
running, for example, would make just the one device null. 

It is possible to specify, instead of just std, something like std=foo. In this case, the stuff on the right-hand side of the equals 
sign specifies a name from /proc/devices, and the major number will be retrieved from there if present. If an entry from / 
proc/devices is specified, the explicit major number may be omitted. In this case, if the number is not found in /proc/ 
devices, attempts to create thedevice will be rqected. 

Inside the braces is a list of specific devices. The name in parenthesis is the "class"; this is something specified in MAKEDEv.cfg 
that determines theownership and permissions of the special filecreated. In the preceding example, the device mem was set to 
havethedass kmem, but nun was set to be public. 0 rdinarily, you'd define public to be mode 666 but kmem to be mode 660 
and owned by group kmem. T he number after the colon is the minor number for this particular device; for instance, 3 for 
null. 

You may also specify a symbolic link with ->. For instance, core was made a link to /proc/kcore. N ote that names may 
contain any characters, but names that contain things other than alphanumerics, dash, and underscore should be put in 
double quotes. 

An entire range of devices can be created. You may specify a range of numbers in brackets: 

tty[1-8] (tty) : 1 

This creates ttyi-tty8 with minor device numbers starting with 1. If you specify the range in hex (prefixed by bx), thedevice 
names will becreated numbered in hex, as is normal for ptys. The range may appear inside the name string, but there may 
only be one range. 
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There isa special syntax for creating the entire banks of devicesfor a hard drive: 

hd[a-d] 8/64 

W hat this means is asfollows Create hda, and eight partitionson hda (hdai through hda8), starting with minor number 0. 
Then create hdb, and eight partitions, starting with minor number 64. Then hdc, and soon, with minor number 64*2 = 
128-and so forth. These are automatically placed in the class disk. The necessary groups and batches are created so you can 
ask makedev to create hd or hda or hdai and expect it to do the correct thing. 

Note that simple arithmetic is permitted for specifying the minor device number, as this often makes things much clearer 
and less likely to be accidentally broken. 

SEE ALSO 

makedev(8), makedev. cfg(5) 

Verson 1.4, January 1995 


environ 

environ— U ser environment. 

SYNOPSIS 

extern char **en»i ron; 

DESCRIPTION 

An array of strings called the envi ronment is made available by exec(2) when a process begins. By convention, these strings 
have the form n a me =v a i ue. Common examples are 

user T he name of the logged-in user (used by some BSD -derived programs). 

logname The name of the logged-in user (used by some System-V derived programs). 

home A user's login directory, set by login(l) from the password file passwd(5). 

lang The name of a locale to use for locale categories when not overridden by lc_all or more 

specific environment variables. 

path The sequence of directory prefixes that sh(l) and many other programsapply in searching 

for a file known by an incomplete pathname. The prefixes are separated by :. 
shell Thefilenameof the user's login shell. 

term Theterminal type for which output isto be prepared. 

Further names maybe placed in the environment by the export command and name=vai ue in sh(l) or bythesetenv command 
if you usecsh(l). Arguments may also be placed in theenvi ronment at the point of an exec(2). 

It is risky practice to set n a me =v a i ue pairs that conflict with well-known shell variables Setting these could cause surprising 
behavior in subshells or system(3) commands. 

SEE ALSO 

login(l), sh(l), bash(l), csh(l), tcsh(l), exec(2), system(3) 
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expire.ctl 

expire. cti— C ontrol file for U senet article expi ration. 



PartV: File Formats 


DESCRIPTION 

Thefile/news/iib/expire.cti isthe default control file for the expire(8) program, which reads it at startup. Blank lines and 
lines beginning with a number sign (#) are ignored. All other lines should be in one of two formats. 

Thefirst format specifies how long to keep a record of fully expired articles. This is useful when anewsfeed intermittently 
offers older news that is not kept around very long. (The case of very old news is handled by the -c flag of ±nnd(8).) There 
should only beonelinein this format, which looks like this: 

/remember/: days 

Where days is a floating-point number that specifies the upper limit to remember a M essage-ID, even if the article has 
already expired. (It does not affect article expirations) 

Most of the lines in the file will consist of five colon-separated fields, as follows 


T he pat t e r n field is comma-separated set of single wiidmat(3)-style patterns that specify the newsgroups to which the rest of 
the line applies Because the file is interpreted in order, the most general patterns should be specified first, and the most 
specific patterns should be specified last. 

The modf i ag field can be used to further limit newsgroups to which the line applies and should be chosen from thefollowing 
set: 

m Only moderated groups 

u 0 nly unmoderated groups 

a All groups 

The next three fields are used to determine how long an article should be kept. Each field should be either a number of days 
(fractions such ass.s are allowed) or the word never. The most common use is to specify the default value for how long an 
article should be kept. Thefirst and third fields- keep and purge- specify the boundaries within which an Expires header 
will be honored. T hey are ignored if an article has no Expires header. T he fields are specified in thefile as "lower-bound 
default upper-bound," and they are explained in this order. Because most articles do not have explicit expiration dates, 
however, the second field tends to be the most important one 

The keep field specifies how many days an article should be kept before it will be removed. No article in the newsgroup will 
be removed if it has been filed for less than keep days, regardless of any expiration date If thisfield is the word never, then an 
article cannot have been kept for enough days so it will never be expired. 

Thedef aui t field specifies how long to keep an article if no Expires header is present. If thisfield is the word never, then 
articles without explicit expiration dates will never be expired. 

The purge field specifies the upper bound on how long an article can be kept. N o article will be kept longer than the number 
of days specified by thisfield. All articles will be removed after they have been kept for purge days If purge is the word never, 
then the article will never be deleted. 

It is often useful to honor the expiration headers in articles, especially those in moderated groups. To do this set keep to zero, 
default to whatever value you want, and purge to never. To ignore any Expires header, set all three fields to the same value. 
There must be exactly one line with a pat tern of * and a modf i ags of a; this matches all groups and isused to set the 
expiration default. 11 should be thefirst expiration line For example: 

## How long to keep expired history 
/remember/:5 

## Most things stay for two weeks 

## Believe expiration dates in moderated groups, up to six weeks 
:M:1:30:42 

## Keep local stuff for a long time 
foo.*:A:30:30:30 



exports 


HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

explre(8), wildmat(3) 

exports 

exports— NFS filesystems being exported. 

SYNOPSIS 

/etc/exports 

DESCRIPTION 

Thefile /etc/exports serves as the access control list for filesystems that can be exported to N FS clients. It is used by both the 
NFS mount daemon mountd(8) and the N FS file server daemon nfsd(8). 

The file format is similar to the SunO S exports file, except that several additional options are permitted. Each linecontainsa 
mount point and a list of machineor ndtgroup names allowed to mount the filesystem at that point. An optional parenthe¬ 
sized list of mount parameters may follow each machine name. Blank lines are ignored, and a# introduces a comment to the 
end of the line 

GENERAL OPTIONS 


link_relative 


link_absolute 

USERID MAPPING 

nfsd bases its access control to files on the server machine on theU ID andGID provided in each N FS RPC request.The 
normal behavior a user would expect is that she can access her files on the server just as she would on a normal filesystem. 

T his requi res that the same UID s and GID s are used on the client and the server machinaThisisnot always true, nor is it 
always desirable. 

Very often, it is not desirable that the root user on a client machine is also treated as root when accessing files on the N FS 
server. To thisend, UID 0 is normally mapped to a different ID : the so-called anonymous or nobody U ID. This mode of 
operation (called root squashing) isthe default and can be turned off with no_root_squash. 

Bydefault, nfsd triesto obtain theanonymousU ID andGID by looking up user nobody in thepassword file at startup 
time. If it isn't found, a UID and G ID of -2 (65534) is used. T hese values can also be overridden bytheanonuid and anongid 
options 

In addition to this nfsd lets you specify arbitrary U IDs and GI Dsthat should be mapped to user nobody as well. Finally, 
you can map all user requests to theanonymousU ID by specifying the aii_squash option. 

For the benefit of installations where U IDsdiffer between different machines, nfsd provides a way to dynamically map server 
UIDsto client UID s and vice versa. This is enabled with the map daemon option and uses the ugid RPC protocol. For this 
to work, you have to run the ugidd{8) mapping daemon on the client host. 


This option requires that requests originate on an Internet port less than ipport_reserved 
(1024). Thisoption ison by default. T0 turn it off, specify insecure. 

Allow only read-only requests on this NFS volume Thedefault is to allow write requests as 
well, which can also be made explicit by using the rw option. 

Convert absolute symbolic links (where the link contents start with a slash) into relative 
links by prepending the necessary number of.. is to gdt from the directory containing the 
link to the root on the server. This has subtle, perhapsquestionable, semantics when thefile 
hierarchy is not mounted at its root. 

Leave all symbolic links as they are Thisisthe default operation. 
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H ere's the complete list of mapping options: 

root_squash M ap requests from UID/GID Oto the anonymous UID/G ID. Note that this does not 

apply to any other UID s that might be equally sensitive, such as user bin. 
no_root_squash T urn off root squashing. This option is mainly useful for diskless clients. 

squash_uids and squash_gids This option specifies a list of UID s or GID s that should be subject to anonymous mapping. 
A valid list of IDs looks like this 


all_squash 


map_daemon 


anonuid and anongid 


squash_uids=0-15,20,25-50 

Usually, your squash lists will look a lot simpler, such as 
squash_uids=0-100 

M ap all UIDsandGIDsto theanonymoususer. Useful for N FS-exported public FTP 
directories, newsspool directories, and so on. The opposite option isno_aii_squash, which is 
the default setting. 

This option turns on dynamic UID/GID mapping. Each UID in an N FS request will be 
translated to the equivalent server U ID, and each UID in an N FS reply will be mapped the 
otherway round. This option requires that rpc.ugidd(8) runs on the client host. The default 
setting is map_identity, which leaves all U ID s untouched. The normal squash options apply 
regardless of whether dynamic mapping is requested. 

These options explicitly set the UID and GID of the anonymous account. This option is 
primarily useful for PC/N FS clients, where you might want all requests appear to be from 
oneuser. As an example consider the export entry for /home/joe in thesection "Example," 
which maps all requests to UID 150 (which issupposedly that of user joe). 


EXAMPLE 

# sample /etc/exports file 
/ master(rw) trusty(rw,no_root_squash) 

/projects proj*.local.domain(rw) 

/usr ‘.local.domain(ro) @trusted(rw) 

/home/joe pc001(rw,all_squash,anonuid=150,anongid=100) 

/pub (ro,insecure,all_squash) 

Thefirst line exports the entire filesystem to rnachinesmaster and trusty. In addition to write access, all UID squashing is 
turned off for host trusty. The second and third entry show examples for wildcard hostnamesand netgroups (this is the 
entry ^trusted). Thefourth line shows the entry for the PC/N FS client discussed previously. The last line exportsthe public 
FTP directory to every host in the world, executing all requests under the nobody account. The insecure option in thisentry 
also allows clients with N FS implementations that don't useareserved portforNFS. 

CAVEATS 

U nlike other N FS server implementations, this nf sd allows you to export both a directory and a subdirectory thereof to the 
same host, for instance /usr and /usr/xi me. I n thiscase, the mount options of the most specific entry apply. For instance 
when a user on the client host accesses a file in /usr/xi i R6, the mount options given in the /usr/xi i R6 entry apply. T his is 
also true when the latter is a wildcard or netgroup entry. 

FILES 

/etc/exports Configuration file for nf sd(8) 

/etc/passwd The password file 

DIAGNOSTICS 

An error parsing the file is reported using sysiogd(8) as level notice from a daemon whenever nf sd(8) or mountd(8) is started. 
Any unknown host is reported at that time, but often not all hosts are not yet known to named(8) at boot time so as hosts are 
found, they are reported with the same sysiogd(8) parameters. 
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SEE ALSO 

mountd(8), nfsd(8), nfs(5), passwd(5) 
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filesystems 

filesystems— Linux filesystem types: minix, ext, ext2, xia, msdos, umsdos, vfat, proc, nfs, iso9660, hpfs, sysv, smb, ncpfs. 


DESCRIPTION 


In thefile/proc/fiiesystems,you can find which filesystems your kernel currently supports (If you need a currently 
unsupported one insert the corresponding module or recompile the kernel.) 

Following is a description of the various filesystems 


umsdos 


iso9660 
High Sierra 


Rock Ridge 






Thefilesystem used in the M inix operating system, thefirst to run under Linux. It hasa number 
of shortcomings: a 64M B partition size limit, short filenames, a single time stamp, and so on. It 
remainsuseful for floppies and RAM disks. 

An elaborate extension of theminix filesystem. It has been completely superseded by the second 
version of the extended filesystem (ext2) and will eventually be removed from the kernel. 

The high performance disk filesystem used by Linuxfor fixed disks as well as removable media. 
The second extended filesystem was designed as an extension of the extended filesystem (ext). 
ext 2 offers the best performance (in terms of speed and C PU usage) of the filesystems supported 
under Linux. 

Designed and implemented to be a stable safe filesystem by extending the M inix filesystem code. 
It provides the basic, most requested features without undue complexity. T he xia filesystem is no 
longer actively developed or maintained. It isused infrequently. 

Thefilesystem used by DOS, Windows, and someOS/2 computers, msdos filenames can be no 
longer than an eight-character name followed by an optional period and three-character 
extension. 

An extended DOSfilesystem used by Linux. It adds capability for long filenames, UID/GID, 
POSIX permissions, and special files (devices, named pipes, and so on) under theDOS 
filesystem, without sacrificing compatibility with DOS. 

Extended D0 S filesystem used by M icrosoft W indows 95 and W indows NT. vfat adds 
capability for long filenames under the M S-D 0 S filesystem. 

A pseudo-filesystem that isused as an interface to kernel data structures rather than reading and 
interpreting /dev/kmem. In particular, its files do not take disk space. Seeproc(5). 

A CD-ROM filesystem type conforming to the I SO 9660 standard. 

Linux supports H igh Sierra, the precursor to the I SO 9660 standard for CD-ROM filesystems It 
is automatically recognized within theiso9660 filesystem support under Linux. 

Linux also supports the System Use Sharing Protocol records specified by the Rock Ridge 
Interchange Protocol. They are used to further describe the files in theiso9660 filesystem to a 
UN IX host and provides information such as long filenames, UID/GID, POSIX permissions, 
and devices It is automatically recognized within theiso9660 filesystem support under Linux. 
TheH igh Performance Filesystem, used in OS/2. Thisfilesystem is read-only under Linux due to 
the lack of available documentation. 

An implementation of the SystemV/Coherent filesystem for Linux. It implements all Xenix FS, 
SystemV/386 FS, and Coherent FS. 

The network filesystem used to access disks located on remote computers. 
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A network filesystem that supports the SM B protocol, used by W indowsfor W orkgroups, 
WindowsNT,and LAN Manager. 

To use smb, you need a special mount program, which can be found in theksmbfs package at 
ftp://sunsite.unc.edu/pub/Linux/systeni/Filesystems/sinbfs. 

A network filesystem that supports the N C P protocol, used by N ovell N etW are 
To usencpfs, you need special programs found at ftp://linuxoi .gwdg.de/pub/ncpfs. 


SEE ALSO 

proc(5), fsck(8), mkfs(8), mount(8) 
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fstab 

fstab— Static information about the filesystems. 

SYNOPSIS 

//include <fstab.h> 

DESCRIPTION 

Thefilefstab contains descriptive information about the various filesystems fstab isonlyread by programs and not written; 
it istheduty of the system administrator to properly create and maintain thisfile. Each filesystem is described on a separate 
line fieldson each line are separated by tabs or spaces. The order of records in fstab is important because fsck(8), mount(8), 
and umount(8) sequentially iterate through fstab doing their thing. 

The first field (fs_spec) describes the block special device or remote filesystem to be mounted. 

The second field (fs_fiie) describes the mount point for thefilesystem. For swap partitions, thisfidd should be specified as 

Thethird field (fs_vfstype) describes thetype of the filesystem. Thesystem currently supports three types of filesystems 
minix A local filesystem, supporting filenamesof length 14 or 30 characters 

ext A local filesystem with longer filenamesand larger inodes. This filesystem hasbeen replaced 

by theext2 filesystem and should no longer be used. 

ext2 A local filesystem with longer filenames larger inodes, and a lot of other features. 

xiafs A local filesystem with longer filenames larger inodes, and a lot of other features. 

msdos A local filesystem for M S-D 0 S partitions 

hpfs A local filesystem for H PFS partitions 

iso9660 A local filesystem used for C D -RO M drives 

nfs A filesystem for mounting partitions from remote systems 

swap A disk partition to be used for swapping. 

If vts_fstype is specified as ignore, the entry is ignored. This is useful to show disk partitions that are currently unused. 

The fourth field (fsjnntops) describes the mount options associated with thefilesystem. 

It isformatted as a comma-separated list of options It containsat least the type of mount plus any additional options 
appropriate to thefilesystem type. For documentation on the available optionsfor non-N FS filesystems, seemount(8). For 
documentation on all N FS-specific options take a look atnfs(5). Common for all types of filesystems are the options noauto 
(do not mount when mount -a isgiven, such as at boot time) and user (allow a user to mount). For more details seemount(8). 
The fifth field (ts_treq) is used for these filesystems by thedump(8) command to determine which filesystems need to be 
dumped. If the fifth field isnot present, a value of zero is returned and dump will assume that thefilesystem does not need to 
be dumped. 



groff_ font 


1127 


The sixth field (fs_passno) is used by thefsck(8) program to determine the order in which filesystem checks are done at 
reboot time. The root filesystem should be specified with a fs_passno of i, and other filesystems should haveats_passno of 2. 
Filesystems within a drive will be checked sequentially, butfilesystemson different drives will be checked atthesametimeto 
utilize parallelism available in the hardware. If the sixth field is not present or zero, a value of zero is returned and fsck will 
assume that the filesystem does not need to be checked. 

The proper way to read records from fstab isto use the routine getmntent(3). 

FILES 

/etc/fstab 

BUGS 

The documentation in mount(8) is often more up-to-date 

SEE ALSO 

getmntent(3), mount(8), swapon(8), nfs(5) 

HISTORY 

The fstab file format appeared in 4.0 BSD. 

Linux0.99, 27 N member 1993 


groffjfont 

groff_font— Format of groff device and font description files 


DESCRIPTION 

T he groff_font format is roughly a superset of the ditroff font format. U nlikethe ditroff font format, there is no associated 
binary format. The font files for device name are stored in a directory devname. There are two types of file: a device description 
file called desc and for each font f , a font fi le called f . T hese are text files; there is no associated binary format. 


DESC FILE FORMAT 

The desc file can contain the following types of lines 




unitwidth n 

tcommand 

sizes si s2 ... sn0 


styles SI S2 ... Sm 
fonts n FI F2 F3 ... Fn 


There are n machine units per inch. 

The horizontal resolution isn machine units 
The vertical resolution isn machine units. 

The scale factor for point sizes. By default, this hasa value of 1. Onescaled point is 
equal to one point/n. The arguments to the unitwidth and sizes commands are 
given in scaled points. 

Q uantities in the font files are given in machine units for fonts whose point size isn 
scaled points 

This means that the postprocessor can handlethet and u output commands. 

This means that thedevicehasfonts at si, s2,... sn scaled points The list of sizes 
must be terminated by ao. Each si can also be a range of sizes m-n. The list can 
extend over more than one line 

Thefirst m font positions will be associated with styles si... sm. 

Fonts fi... Fn will be mounted in thefont positionsm+l,... ,m4n where misthe 
number of styles This command may extend over more than one line. A font name 
of 0 will cause no font to be mounted on the corresponding font position. 
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family fa| The default font family isf a m. 

charset This line and everything following in thefile are ignored. 11 isallowed for the sake of 

backwards compatibility. 

The res, unitwidth, fonts, and sizes lines are compulsory. Other commands are ignored by troff but may be used by 
postprocessors to store arbitrary information about the device in the desc file. 

FONT FILE FORMAT 

A font file has two sections. The first section is a sequence of lines, each containing a sequence of blank delimited words; the 
first word in the line is a key, and subsequent words give a value for that key. 
name f The name of the font isF. 

spacewidth n The normal width of a space isn. 

slant n The characters of the font have a slant of n degrees. (Positive meansforward.) 

ligatures ligi iig 2 ... lign [ 0 ] Characters ligi, iig 2 ,... ,iign are ligatures; possible ligatures are ff, ft, fi, and ffi. 

For backwards compatibility, the list of ligatures may be terminated with a 0. The 
list of ligatures may not extend over more than one line. 

special Thefont is special; this meansthat when a character is requested that is not present 

in the current font, it will be searched for in any special fonts that are mounted. 

Other commands are ignored by troff but may be used by postprocessors to store arbitrary information about the font in the 
font file 

Thefirst section can contain comments, which start with the# character and extend to the end of a line. 

The second section contains one or two subsections. It must contain a charset subsection and it may also contain a kernpairs 
subsection. These subsections can appear in any order. Each subsection starts with a word on a line by itself. 

The word charset startsthe charset subsection. The charset line isfollowed by a sequence of lines Each linegives 
information for one character. A line comprises a number of fields separated by blanks or tabs The format is 


name identifies the character: if name isasinglecharacterc, it corresponds to the groff input character c; if it is of the form \c 
where c is a single character, then it corresponds to the groff input character nc; otherwise it corresponds to the groff input 
character \ [name] (if it is exactly two characters**, it can be entered as\(*x). groff supports eight-bit characters however, 
some utilities have difficulties with eight-bit characters For this reason, there isa convention that the name charn is 
equivalent to the single character whose code is n. For example chari63 is equivalent to the character with code 163, which is 
the pounds sterling sign in ISO Latin-1. The name— is special and indicates that the character is unnamed; such characters 
can only be used by means of the \n escape sequence in troff. 

Thetype field gives the character type: 

1 T he character has an descender, such as p. 

2 The character has an ascender, such as b. 

3 The character has both an ascender and a descender, such as <. 

The code field gives the code that the postprocessor uses to print the character. The character can also be input to groff using 
thiscodeby meansof the \n escape sequence. The code can beany integer. If it startswith a 0, it will be interpreted as octal; 
if it starts with 0xor0x.it will beinterpreted as hexadecimal. 

Anything on the line after the code field will beignored. 

The met r i cs field hastheform: 

width[,height[,depth!,italic_correction[,left_italic_correctlon 
*[,subscript.correction]]]]] 

There must not be any spaces between these subfields. M issingsubfieidsareassumed to be 0. The subfields are all decimal 
integers Because there is no associated binary format, these values are not required to fit into a variable of type char as they 
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are in ditroff.Thewi dth subfields gives thewidth of the character. The hei ght subfield gives the height of the character 
(upwards is positive); if a character does not extend above the baseline, it should be given a zero height, rather than a negative 
height. The depth subfield gives the depth of the character, that is, the distance below the lowest point below the baseline to 
which the character extends (downwards is positive); if a character does not extend below above the baseline, it should be 
given a zero depth, rather than a negative depth. T he i t a i i c.cor recti on subfield givesthe amount of space that should be 
added after the character when it is immediately to be followed by a character from a roman font. T he 
left _i tai i ccorrecti on subfield gives the amount of space that should be added before the character when it is immediately 
to be preceded by a character from a roman font. Thesubscript_correction gives the amount of space that should be added 
after a character before adding a subscript. This should be less than thei tai i c.cor recti on. 

A linein the charset section can also havetheformat 


This indicates that name isjust another name for the character mentioned in the preceding line 
The word kernpairs starts the kernpairs section. Thiscontains a sequence of linesof theform: 

cl c2 n 

This means that when character ci appears next to character c 2 , the space between them should be i ncreased by n. M ost 
entries in kernpairs section will have a negative value for n. 

FILES 

/usr/nb/groff/font/dev name/DESc D evice description filefor device name. 

/usr/iib/groff/font/devname/F Font filefor font f of device name. 

SEE ALSO 

groff_out(5), gtroff(l) 

GroffVersion 1.09,14 February 1994 


groff_out 

groff_out— groff intermediate output format. 

DESCRIPTION 

This manual page describes the format output byGNU troff. The output format used byGNU troff is very similar to that 
used by UN IX device-independent troff . Only the differences are documented here. 

The argument to the s command is in scaled points (unitsof points, where n isthe argument to thesizescaie command in 
the desc file.) The argument to thex H eight command is also in scaled points 
Thefirst three output commands are guaranteed to be 


If the tcommand line is present in the desc file troff will use the following two commands 

txxx xxx is any sequence of characters terminated by a space or a newline thefirst 

character should be printed at the current position, the current horizontal position 
should be increased by the width of the first character, and soon for each character. 
Thewidth of the character is that given in thefont file appropriately scaled for the 
current point size and rounded so that it is a multiple of the horizontal resolution. 
Special characters cannot be printed using this command. 
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unxxx This is same as the t command except that after printing each character, the current 

horizontal position is increased by the sum of the width of that character and n. 

Note that single characters can have the eighth bit set, as can the names of fonts and special characters. 

T he names of characters and fonts can be of arbitrary length; drivers should not assume that they wi II be only two characters 
long. 

When a character isto be printed, that character will always be in the current font. U nlike device-independent troff, it is not 
necessary for drivers to search special fonts to find a character. 

T he d drawing command has been extended. These extensions will not be used by GN U pic if the -n option is given. 

Df rftii Set the shade of gray to be used for filling solid objects to n;n must bean integer 

between 0 and 1000, where 0 corresponds to solid white and 1000 to solid black and 
valuesin between correspond to intermediate shades of gray. This applies only to 
solid circles, solid ellipses, and solid polygons By default, a level of 1000 will be 
used. W hatever color a solid object has, it should completely obscure everything 
beneath it. A value greater than 1000 or less than 0 can also be used: This means fill 
with the shade of gray that is currently being used for lines and text. N ormally, this 
will be black, but some drivers may provide a way of changing this 
dc M D raw a solid circle with a di ameter of d with the leftmost point at the current 

position. 

de dx dy\n D raw a solid ellipse with a horizontal diameter of dx and a vertical diameter of dy 

with the leftmost point at the current position. 

Dp dxi dyi d x 2 dy2 ... dxn dyttir D raw a polygon with, for i =1,.... n+1, the i th vertex at the current position + 
I^ifdxi, dyj). At the moment, G N U pic only uses this command to generate 
triangles and rectangles 

dp dxi dyi dx 2 dy2 ... dxpdptn Like Dp, but draw a solid rather than outlined polygon. 

Dt Set the current line thickness to n machineunits. Traditionally, UNIX troff drivers 

use a line thickness proportional to the current point size; drivers should continue to 
do this if no Dt command has been given or if a Dt command has been given with a 
negative value of n . A zero value of n selects the smallest available line thickness. 

A difficulty arises in how the current position should be changed after the execution of these commands. This is not of great 
importance because the code generated by GN U pic does not depend on this Given a drawing command of the form 

where c is not one of c, e, I, a, or ~, UNIX troff will treat each ofthexi asa horizontal quantity and each of they i as a 
vertical quantity and will assume that the width of the drawn object is Eli x and that the height is Eli yi. (The 
assumption about the height can be seen by examining the st and sb registers after using such a D command in a \w escape 
sequence.) This rule also holdsfor all theoriginal drawing commands with theexception of De. F or the sake of compatibil¬ 
ity, GN U troff also follows this rule, even though it produces an ugly result in the case of the Df, Dt, and, to a lesser extent, 

D E commands Thus after executing a D command of theform 

Dc xl yl x 2 y 2 ... xn yi!® - 

thecurrent position should beincreased by (EL xi; Eli yi). 

A continuation convention permits the argument to the x X command to contain newlines; when outputting the argument 
to thex X command, GN U troff will follow each newlinein the argument with a + character (as usual, it will terminate the 
entire argument with a newline); thus if the line after the line containing thex X command starts with +, then the newline 
ending the line containing thex X command should be treated as part of the argument to thex X command, the + should be 
ignored, and the part of the line following the + should be treated like the part of the linefollowing the x X command. 
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SEE ALSO 

groff_font(5) 
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group 

group— User group file. 

DESCRIPTION 

/etc/group isan ASCII file that defines the groups to which users belong. There is one entry per line, and each line has the 
format 

group_name :passwd :GI D:user_l i st 

The field descriptions are 

group, name T he name of the group. 

passwd The (encrypted) group password. If thisfield isempty, no password is needed. 

GiD The numerical group ID. 

user j i st All the group member's usernames, separated by commas 

FILES 

/etc/group 

SEE ALSO 

login(l), newgrp(l), passwd(5) 

Linux, 29 December 1992 


history 

history— Record of current and recently expired U senet articles. 

DESCRIPTION 

Thefile/news/iib/history keeps a record of all artidescurrently stored in the news system, as well as those that have been 
received but since expired. 

The file consists of text lines. Each line corresponds to one article Thefile is normally kept sorted in the order in which 
articles are received, although this isnot a requirement. tnnd(8) appends a new line each time it files an article and exptre(8) 
builds a new version of the file by removing old articles and purging old entries 
Each line consists of two or three fields separated by a tab, shown below as\t: 

<Message-1 D>\t date 

<Message -1 D>\t date \t files 

The Message-i d field isthe value of theartideisM essage-l D header, including the angle brackets. 

The dat e field consists of three subfields separated byatilde All subfields are the text representation ofthenumber of 
seconds since the epoch— a time_t; see gettimeofday(2). T hefirst subfield isthe article's arrival date. If copies of the article 
are still present, then the second subfield is either the value of the article's Expires header or a hyphen if no expiration date 
was specified. If an article has been expired, the second subfield will bea hyphen. The third subfield is the value of the 
article's D ate header, recording when the article was posted. 
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Thef i i es field is a set of entries separated by one or more spaces Each entry consists of the name of the newsgroup, a slash, 
and the article number. Thisfield isempty if the article has been expired. 

For example, an article cross-posted to comp, sources, unix and comp, sources, d that was posted on February 10,1991, (and 
received three minutes later) with an expiration date of M ay 5,1991, could have a history line (broken into two linesfor 
display) like the following: 

<312@litchi.foo.com> \t 666162000'673329600'666162180 
\t comp.sources.unix/1104 comp.sources.d/7056 

In addition to the text file, there is a dbz(3z) database associated with the file that uses the M essage-ID field as a key to 
determine the offset in the text file where theassociated line begins For historical reasons, the key includes the trailing \o 
byte (which is not stored in the text file). 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

dbz(3z), expire(8), innd(8), news-recovery(8) 

hosts.nntp,hosts.nntp.nolimit 

hosts, nntp, hosts, nntp. noiimit— List of hosts that feed NNTP news 

DESCRIPTION 

Thefile/news/iib/hosts.nntpisreadby innd(8) to get the list of hosts that feed the local site Usenet news using the N N TP 
protocol. The server reads this file at startup or when directed to by ctiinnd(8). When a hosts connects to theN NTP port of 
the system on which innd is running, the server will do a check to see if their Internet address is the same as one of the hosts 
named in this file. If the host is not mentioned, then innd will spawn an nnrpd(8) to process the connection, with the 
accepted connection on standard input and standard output. 

Comments begin with a number sign (#) and continue through the end of the line Blank lines and comments are also 
ignored. All other lines should consist of two or three fields separated byacolon. 

Thefirst field should be either an Internet address in dotted-quad format or an address that can be parsed by 
gethostbyname(3). If a host’s entry has multiple addresses, all of them will be added to the access list. The second field, which 
may be blank, isthe password theforeign host is required to use when first connecting. The third field, which may be 
omitted, isa list of newsgroups to which the host may post articles. This list is parsed asanewsfeeds(5) subscription list; 
groups not in the list are ignored. 

Because innd is usually started at system boot time, the local nameserver may not be fully operational when innd parses this 
file. As a work-around, a ctiinnd reload command can be performed after a delay of an hour or so. It is also possible to 
provide both a host's name and its dotted-quad address in the file 
For example: 

## FOO has a password, UUNET doesn't. 

## UUNET cannot post to local groups. 

## These are comment lines, 
news.too.com:magic 

If the file contains passwords, it should not be world-readable. T he file /news/iib/hosts. nntp. noiimit, if it exists, is read 
whenever the hosts, nntp file is read. It has the same format, although only thefirst field is used. Any host mentioned in this 
file is not subject to the incoming connections limit specified by innd’s -c flag. This can be used to allow local hosts or time- 
sensitive peers to connect regardless of the local conditions. 



HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

ctlinnd(8), lnnd(8), nnrpd(8) 

hosts_access 

hosts_access— Format of host access control files 

DESCRIPTION 

This manual page describes a simple access control language that isbased on client (hostnam^address, username) and server 
(process name) patterns Examples are given at the end. The impatient reader can skip to the "Examples" section for a quick 
introduction. 

In the following text, daemon is the process name of a network daemon process and client is the name or address of a host 
requesting service. Network daemon process names are specified in theinetd configuration file. 

ACCESS CONTROL FILES 

The access control software consults two files Thesearch stops at the first match: 

Access will be granted when a (d a e mo n ,c i i ent) pair matches an entry in the/etc/hosts, allow file 
Otherwise, access will be denied when a (daemon.c i i ent) pair matches an entry in the/etc/hosts, deny file 
Otherwise, access will be granted. 

A non-existing access control file is treated as if it were an empty file Thus, access control can be turned off by providing no 
access control files 

ACCESS CONTROL RULES 

Each access control file consists of zero or more lines of text. These lines are processed in order of appearance. Thesearch 
terminates when a match isfound. 

A newline character is ignored when it is preceded by a backslash character. 

Blank lines or lines that begin with a # character areignored. 

All other lines should satisfy thefollowing format, things between n being optional: 

daemon. i st : c! i ent .1 s t [ : shell .command ] 

daemon.iist is a list of one or more daemon process names (argvia] values) or wildcards 

ci i ent. i i st is a list of one or more hostnames, host addresses patterns or wildcards that will be matched against the remote 
hostname or address 

List elements should be separated by blanks or commas. 

With the exception of N IS (YP) netgroup lookups, all access control checks are case insensitive. 

PATTERNS 

The access control language implements thefollowing patterns 

A string that begins with a . character: A client name or address is matched if its last components match the specified 
pattern .For example, the pattern . tue. m matches the hostname wzv. win. tue. m. 

A string that ends with a . character: A client name or addressis matched if its first fields match the given string. For 
example, the pattern 131 . 155 . matches the address of (almost) every host on the Eindhoven University network 

( 131 .155.x .X ). 
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A string that begins with a e character is treated asanetgroup name: Netgroups are usually supported on systems with N IS 
(formerly YP) databases A client hostname is matched if it isa(host) member of the specified ndtgroup. 

An expression of theform n .n .n .n/m.m.m.m is interpreted asa net/mask pair. A client addressis matched if net isequal to the 
bitwise and of the address and themask. For example, the net/mask pattern 131 . 155 . 72 . 0 / 255 . 255 . 254.0 matches every address 
in the range 131 . 155 . 72.0 through 131 . 155 . 73 . 255 . 


WILDCARDS 


The access control language supports explicit wi Idcards: 


ALL 

LOCAL 

UNKNOWN 

KNOWN 

FAIL 


If thistoken appears in a daemon list, it matches all network daemon process names. If theALL 
token appears in a client list, it matches all client names and addresses. 

M atches any string that does not contain a dot character. Typical use is in client lists 
M atches any host whose name or address are unknown. Should be used with care Hostnames 
may be unavailable due to temporary nameserver problems. A network address will be 
unavailable when the software cannot figure out what type of network it is talking to. 

M atches any host whose name and address are known. Should be used with care: H ostnames 
may be unavailable due to temporary nameserver problems. A network address will be 
unavailable when the software cannot figure out what type of network it istalking to. 

Like theALL wildcard but causes the software to pretend that the scan of the current access 
control table fails, fail is being phased out; it will become an undocumented feature. The 
except operator is a much cleaner alternative. 


OPERATORS 

except Intended use is of theform: 1 i $t_i except i i st_ 2 ;thisconstructmatchesanythingthat 

matchesi i st _ 1 unless it matches 1 i s t _ 2 . T hisconstruct can be used in daemon lists and in 
client lists. The except operator can be nested: If the control language would permit the use 
of parentheses, a except b except c would parse as (a except (b except c)). 

SHELLCOMMANDS 

If the first-matched access control rule contains a shell command, that command is subjected to the following substitutions: 
%a Expands to the remote host address. 

%c Expands to client information: user @host, user @ad dr ess, a hostname or just an address, 

depending on how much information is available 

%h Expandsto the remote hostname (or address, if the hostname is unavailable). 

%d Expandsto the daemon process name (argvioi value). 

%p Expandsto the daemon process ID. 

%u Expandsto the remote username (or unknown). 

%% Expandsto a single % character. 

Characters in % expansionsthat may confuse the shell are replaced by underscores. The result isexecuted by a /bin/sh child 
process with standard input, output, and error connected to /dev/nuii. Specify an & at theend of thecommand if you do not 
want to wait until it has completed. 

Shell commands should not rely on the path setting of the inetd. Instead, they should use absolute pathnames, or they 
should begin with an explicit PATH=whatever statement. 

REMOTE USERNAME LOOKUP 

When the client host supports the RFC 931 protocol or one of its descendants (tap, ident) the wrapper programs can 
retrieve additional information about the owner of a connection. When available, remote username information is logged 
together with the client hostname and can be used to match patterns like 





The daemon wrappers can be configured at compile time to perform rule-driven username lookups (default) or to always 
interrogate the client host. In the case of rule-driven username lookups, the preceding rule would cause username lookup 
only when both the daemon j i st and theho s t _ pa t tern match. 

A user pattern hasthe same syntax as a daemon process name hostname or host address pattern, so the same wildcards and 
so on apply (but netgroup membership of users is not supported). One should not get carried away with username lookups, 
however. 

The remote username information cannot be trusted when it is needed most—that is when the remote system has been 
compromised. In general, all and (un)known are the only username patterns that make sense. 

U sername lookups are possible only with TC P-based services and only when the client host runs a suitable daemon; in all 
other cases the result is unknown. 

A well-known UN IX kernel bug may cause loss of service when username lookups are blocked by a firewall. The wrapper 
readme document describes a procedure to find out if your kernel has this bug. 

U sername lookups cause noticeable del ays for PC users. T he default time-out for username lookups is ten seconds too short 
to cope with slow networks but long enough to irritate PC users. 

Selective username lookups can alleviate the last problem. For example a rule like 

daemon,! i st : Cpcnetgroup ALLCALL 

would match members of thepc net group without doing username lookups but would perform username lookups with all 
other systems 

EXAMPLES 

The language isflexible enough that different types of access control policy can be expressed with a minimum of fuss. 
Although the language uses two access control tables the most common policies can beimplemented with one of the tables 
being trivial or even empty. 

When reading thefollowing examples it is important to realize that the allow table is scanned before the deny table that the 
search terminates when a match is found, and that access is granted when no match isfound at all. 

Theexamples use host and domain names They can be improved by including address or network/netmask information to 
reduce the impact of temporary nameserver lookup failures. 

MOSTLY CLOSED 

In this case access is denied by default. Only explicitly authorized hosts are permitted access 
The default policy (no access) is implemented with a trivial deny file: 

/etc/hosts.deny: 


Thisdenies all serviceto all hosts unless they are permitted access by entries in theallow file. 

The explicitly authorized hosts are listed in theaiiow file: 

/etc/hosts.allow: 

ALL: LOCAL @some_netgroup 

ALL: .foobar.edu EXCEPT terminalserver.foobar.edu 

Thefirst rule permits access to all servicesfrom hosts in the local domain (no . in the hostname) and from members of the 
some, net group netgroup. The second rule permits access to all servicesfrom all hosts in the.foobar.edu domain, with the 
exception Of terminalserver.foobar.edu. 

MOSTLY OPEN 

Here, access is gran ted by default; only explicitly specified hosts are refused service. 
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Thedefault policy (accessgranted) makestheallow file redundant so that it can beomitted. The explicitly non-authorized 
hosts are listed in the deny file: 

/etc/hosts.deny: 

ALL: some.host.name, .some.domain 

ALL EXCEPT in.fingerd: other.host.name, .other.domain 

Thefirst rule denies some hosts all services; the second rule still permits finger requests from other hosts 

BOOBY TRAPS 

The next example permits tftp requests from hostsin the local domain. Requests from any other hosts are denied. Instead of 
the requested file a finger probeissentto the offending host. The result is mailed to the superuser. 

/etc/hosts.allow: 
in.tftpd: LOCAL, .my.domain 
/etc/hosts.deny: 

in.tftpd: ALL: (/some/where/safe_finger -1 @%h \ \ 

/usr/ucb/mail -s %d-%h root) & 

The safe_finger command comes with thetcpd wrapper and should be installed in a suitable place. It limits possible damage 
from data sent by the remote finger server. It gives better protection than the standard finger command. 

Theexpansion of the%h (remote host) and %d (service name) sequences is described in thesection on shell commands. 
Warning: Do not booby-trap your finger daemon, unless you are prepared for infinite finger loops. 

On network firewall systems, this trick can be carried even further. The typical network firewall only provides a limited set of 
services to the outer world. All other services can be "bugged" just like the preceding tftp example. The result is an excellent 
early-warning system. 

DIAGNOSTICS 

An error is reported when a syntax error is found in a host access control rule, when the length of an access control rule 
exceeds the capacity of an internal buffer, when an access control rule is not terminated by a newline character, when the 
result of %<char act er> expansion would overflow an internal buffer, and when a system call fails that shouldn't. All problems 
are reported via the sysiog daemon. 

FILES 

/etc/hosts, allow, (daemon ,c i i ent ) pairs that are granted access 
/ etc / hosts. de ny, ( d a e mo n ,c I i e n t ) pai rs that are den i ed access 

SEE ALSO 

tcpd(8), TCP/IP daemon wrapper program 

BUGS 

If a nameserver lookup times out, the hostname will not be available to the access control software, even though the host is 
registered. 

Domain nameserver lookups are case insensitive; N IS (formerly YP) netgroup lookups are case sensitive. 

AUTHOR 

WidtseVenema (wietse@wzv.win.tue.ni), Department of M athematicsand Computing Science, Eindhoven University of 
Technology, Den Dolech 2, P.O. Box 513, 5600 M B Eindhoven, The Netherlands. 
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hosts_options 

hosts_options— Host access control language extensions 

DESCRIPTION 

This document describes optional extensions to the language described in the hosts_access(5) document. The extensions are 
enabled at program build time by editing the makefile 
The extensible language uses the following format: 

daemonl i st : clientjist : option : option ... 

Thefirst two fields are described in thehosts_access(5) manual page. The remainder of the rules is a list of zero or more 
options Any : characters within optionsshould be protected with a backslash. 

An option isoftheform keyword or keywor d = value. Optionsare processed in thespecified order. With someoptions,the 
value issubjected to %<char act er > substitutions. 

OPTIONS 

seventy = mail.info Change the severity level at which theevent will belogged. Facility names (such as 

mail) are optional and are not supported on systems with older sysiog implementa¬ 
tions. The severity option can be used to emphasize or to completely ignore specific 
events 

allow (deny) Grant (deny) service even when the matched rule was found in thehosts.deny 

(hosts. allow) file T hese options must appear at the end of a rule. 

With the allow and deny keywords, it is possible to keep all access control rules within a single file-for example in the 
hosts.allow file: 

ALL: .friendly.domain: allow 
ALL: ALL: deny 

This permits access from specific hosts only. 0 n the other hand, 

ALL: .trouble-makers: deny 
ALL: ALL: allow 

This permits access from all hosts except a few troublemakers, 
twist = shell_command 


in.ftpd : ... : twist = /bin/echo 421 

in.telnetd : ... : twist = PATH=/some/other; exec in.telnetd 


spawn = shell_command 


Replace the current process by an instance of the 
specified shell command, after performing the 
%<c har act er > expansions described in the 
hosts_access(5) manual page stdin, stdout, and 
stderr are connected to the remote client process 
This option must appear at the end of a rule 
Examples 

Some bounce message sends a customized bounce 
message to the remote client instead of running the 
real FTP daemon. 

Runs /some/other/in.telnetd Without polluting its 
command-line array or its process environment. 
Warning: In case of U D P services do not twist into 
commandsthat use the standard I/O or the 
read(2)/write(2) routines to communicate with the 
client process U D P requires other I/O primitives. 
Execute the shell command in a child process after 
performing the %<c h a r a c t e r > expansionsdescribed 
in thehosts_access(5) manual page. The command 
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spawn = (/some/where/safe_finger -1 @%h | /usr/ucb/mail root) & 


umask = 022 


keepalive 


linger = number_of_seconds 


nice (no argument) 


user = nobody 


group = tty 


is executed with stdin, stdout, and stderr 
connected to the null device so that it won't mess 
up the conversation with the remote host. Example: 
Executes, in a background child process, theshell 
command safe_finger -1 @%h | mail root after 
replacing %h by the name or address of the remote 
host. 

The example uses the sat e_f inger command 
instead of the regular finger command to limit 
possible damage from data sent by thefinger server. 
T he safe_f inger command is part of the daemon 
wrapper package; it is a wrapper around the regular 
fi nger command that filters the data sent by the 
remote host. 

Like the umask command that is built into theshell. 
An umask of 022 prevents the creation of files with 
group and world write permission. The umask 
argument should bean octal number. 

C auses the server to periodically send a message to 
thedient. The connection isconsidered broken 
when the client does not respond. The keepalive 
option can be useful when users turn off their 
machine while it is still connected to a server. T he 
keepalive option is not useful for datagram (U D P) 
services 

Specifies how long the kernel will try to deliver not- 
ydt delivered data after the server process closes a 
connection. 


C hange the nice value of the process (default 10 ). 
Specify a positive value to spend more C PU 
resources on other processes. 

Assume the privileges of the nobody account. This is 
useful with inetd implementations that run all 
serviceswith root privilege. It isgood practice to 
run services such as finger at a reduced privilege 
level. 

Assume the privileges of the tty group. T his is 
useful mostly in combination with the user option. 

I n order to switch both user and group ID s, a/vitch 
group ID before switching user ID. 

Placea (name, vai ue } pair into the process environ¬ 
ment. Theval ue is Subjected to %<c haracter > 
expansions and may contain whitespace (but 
leading and trailing blanks are stripped off). 

W arning: M any network daemons reset their 
environment before spawning a login or shell 
process 
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Look up the remote user name with the RFC 931 
(ident and so on) protocol. Thisoption issilently 
ignored in case of services based on transports other 
than TCP. It requires that theclient system runsan 
RFC 931 (ident and so on) compliant daemon and 
may cause noticeable del ays with connectionsfrom 
non-U NIX hosts. The time-out period isoptional. 

If no time-out is specified, a default value is taken. 

DIAGNOSTICS 

W hen a syntax error isfound in an access control rule, the error is reported to thesysiog daemon; further options will be 
ignored, and service is denied. 

SEE ALSO 

hosts_access(5), the default access control language 

AUTHOR 

WidtseVenema (wietse@wzv.win.tue.nl), Department of M athematicsand Computing Science, Eindhoven University of 
Technology, Den Dolech 2, P.O. Box 513, 5600 M B Eindhoven, The Netherlands. 

inittab 

inittab— Format ofthe inittab file used bytheSy^/-compatibleinit process. 

DESCRIPTION 

The inittab file describeswhich processes are started at bootup and during normal operation (such as/etc/rc, gettys). imt 
distinguishes multiple run levels, of which each can have its own set of processes that are started. Valid run i evei s are 0-6 and 
a, b, and c for ondemand entries. An entry in the inittab file hasthefollowing format: 

Lines beginning with # are ignored. 

i d A uniquetwo-character-sequence which identifiesan entry in inittab. 

Note: For gettys or other login processes, the i d field should be the tty suffix of the 
corresponding tty, such as 1 for tty 1 . Otherwise, the login accounting will not work 
correctly. Thisisa bug in login and will be fixed. 

runi evei s D escri bes i n which run levels the specified action should betaken, 

action Describeswhich action should betaken. 

process Specifies the process to beexecuted. If theprocessfield starts with a + character, intt will 

not do utmp and wtmp accounting for that process. T his is needed for gettys that insist on 
doing their own utmp/wtmp housekeeping. This is also a historic bug. 

Valid actions are 

respawn The process will be restarted whenever it terminates (such asgetty). 

wait The process will be started once when thespecified run level isentered and tnit will wait 

for its termination. 

once The process will beexecuted once when thespecified run level isentered. 

boot The process will beexecuted during system boot. The run level field isignored. 
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The process will be executed during system boot while imt waits for its termination (such 
as/eto/rc). Theruni evei field isignored. 

Thisdoes nothing. 

A process marked with ondemand will be executed whenever the specified ondemand run level 
is called. However, no r uni evei change will occur. 

An initdefauit-entry specifies the run level that should be entered after system boot. If 
none exists, init will ask for a r uni evei on the console. 

The process will be executed during system boot. It will be executed before any boot or 
bootwatt entries. 

The process will be executed when init receivesthesiGPWR signal, indicating that there is 
something wrong with the power, init will wait for the process to finish before continuing. 
Aspowerwait but init will not wait for the processes completion. 

The process will be executed when init receivesthesiGPWR signal, provided there is a file 
called /etc/powerstatus containing the word ok. T his meansthat the power has come back 
again. 

The process will be executed when init receivesthe sigint signal. Thismeans that someone 
on the system console pressed the Ctrl-tAlt-tO el key combination. Typically, one wants to 
execute some sort of shutdown either to get into single-user level or to reboot the machine. 

Theruni evei field may contain multiple characters for different run levels, such as 123 if the process should be started in run 
levels 1, 2 and 3. ondemand entries may contain an a, b, ore. Theruni evei field of sysinit, boot, and bootwait entries are 
ignored. 

When the run level is changed, any running processes that are not specified for the new run level are killed, first with sigterm 
and then with sigkill. 

EXAMPLES 

Thisisan example of an inittab that resembles the old Linux inittab: 



1:1:respawn:/etc/getty 9600 ttyl 
2:1:respawn:/etc/getty 9600 tty2 
3:1:respawn:/etc/getty 9600 tty3 
4:1:respawn:/etc/getty 9600 tty4 

This inittab fileexecutes /etc/rc during boot and startsgettys on ttyi-tty4. 
A more elaborate inittab with different run levels(seethecommentsinside) is 



# level 1: getty on ttyl 

# level 2: getty on ttyl-4 

# level 3: ttyl-4, dialin via modem(ttys2) 

# level 4: ttyl-4, ttyb 



1:1234:respawn:/etc/getty 9600 ttyl 
2:234:respawn:/etc/getty 9600 tty2 
3:234:respawn:/etc/getty 9600 tty3 










4:234:respawn:/etc/getty 9600 tty4 
s2:3:respawn:/etc/mgetty ttys2 19200 
b:4:respawn:/etc/getty 19200L ttyb 
ca::ctrlaltdel:/etc/shutdown -t3 -rf n 


FILES 

/etc/inittab 

AUTHOR 

init was written by M iquel van Smoorenburg (miqueis@drinkei.ni.mugnet.org). The manual page was written by Sebastian 
Lederer (lederer@francium.informatik.uni-bonn.de) and modified by M ichael H aardt (u31 b3hs@pool. informatik.rvith- 
aachen.de). 

SEE ALSO 

init(8), telinit(8) 
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inn.conf— Configuration data for I nterN etN ews programs. 

DESCRIPTION 

Thefile /news/iib/inn.conf isused to determine various parameters. Blank lines and lines starting with a number sign (#) are 
ignored. All other lines specify parameters that may be read and should be of the following form: 

name : [optional whitespace] value 

Everything after the whitespace and up to the end of the line istaken asthevai ue; multi-word values should not be put in 
quotes. The case of names is significant; server is not the same as server or server. 

Some parameters specified in thefile may be overridden by environment variables, and some file parameters may be used to 
mask real data,such as when hiding a cluster of hosts behind a single electronic mail hostname. The current sdt of parameters 
is as follows: 

fromhost 

moderatormailer 

organization 
pathhost 

server 


This is the name of the host to use when building the F rom header line. T he default isthe 
fully qualified domain name of the local host. The value of the fromhost environment 
variable if it exists, overrides this 

This names the default machine that containsforwarding aliases for all moderated groups. It 
is only used if themoderators(5) file doesn't exist or if the group is not matched by that file 
The value is interpreted asa pattern match; see moderators(5). 

This specifies what to put in the 0 rganization header if it is blank. The value of the 
organization environment variable if it exists overrides this 

This specifies how to namethe local site when building the Path header line The default is 
thefully qualified domain name of the local host. 

This specifies the name of the N NTP server to which an article should be posted. The value 
of the nntpserver environment variable, if it exists, overrides this. 

This should be the domain name of the local host. It should not have a leading period, and 
it should not be a full host address. It isused only if theGetFQDN routine in iibinn(3) cannot 
get thefully qualified domain name by using either the gethostname(2) or gethostbyname(3) 
calls Thecheck isvery simple; if either routine returns a name with a period in it, then it is 
assumed to havethefull domain name. 
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Three parameters are used only by nnrpd when accepting postingsfrom clients 

mime-version If this parameter is present, then nnrpd will add the necessary MIME (M ultipurpose Internet 

M ail Extensions) headers to all any articles that do not have a M ime-Version header. This 
parameter specifies the M IM E version and should normally be i . 0 . 
mime-contenttype If M IM E headers are being added, this parameter specifies the value of the Content-Type 

header. Thedefault value is text/piain; charset=us-Ascn. 
mime-encoding If M IM E headers are being added, thisparameter specifies the value of theContent- 

T ransfer-Encoding header. Thedefault valueis7bit. 

Note that this file can be identical on all machinesin an organization. 


EXAMPLE 

fromhost: 

moderatormailer: 

organization: 

#pathhost: 

server: 


Foo, Incorporated 


Thisfile is intended to be fairly static; any changes made to it are typically not reflected until a program restarts. 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

libinn(3), moderators(5) 

innwatch.ctl 

innwatch.ctl— Control USenet supervision by innwatch. 

DESCRIPTION 

Thefile/news/iib/innwatch.cti isused to determine what actions are taken during the periodic supervisions by innwatch. 
Thefile consistsof a series of lines; blank lines and lines beginning with a number sign (#) areignored. All other lines consist 
of seven fields, each preceded by a delimiting character: 

:label:state:condition:te st:limit:command:reason 

The deli miter can be any one of several non-alphanumeric characters that does not appear elsewhere in the line; there is no 
way to quote it to include it in any of the fields Any of!,,,:, @,;, or? is a good choice Each line can have a different 
delimiter; thefirst character on each line is the delimiter for that line W hitespace surrounding delimiters, except before the 
first, is ignored and does not form part ofthefields whitespace within fields is permitted. All delimiters must be present. 
Thefirst field is a label forthecontrol line. It is used as an internal state indicator and in ctiinnd messages to control the 
server. If omitted, the line number is used. 

The second field specifieswhen thiscontrol lineshould be used. It consists ofa list of labels and special indicatorsseparated 
by whitespace. If the current state matches against any of the labels in thisfield, this line will be used as described below. The 
values that may be used are 

Thislinematchesifthecurrentstateisthesameasthelabel on thisline or if the current state 
is run, the initial state. This is also thedefault state if thisfield is empty. 
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label 


-label 


This line matches if the current state is run. 

T his line always matches. 

T his li ne matches if the current state is the specified label, 
This line matches if the current state is not the specified i a 


The third field specifies a shell command that is invoked if this line matches Do not use any shell filename expansion 
characters such as *, ?, or [ (even quoted, they're not likely to work as intended). If the command succeeds as indicated by 
its exit status it is expected to have printed a single integer to standard output. This gives the value of this control line, to be 
used below. If the command fails the line is ignored. The command is executed with itscurrent directory sdt to the 
newsspool directory, /news/spooi. 

The fourth field specifies the operator to use to test the value returned above. It should be one of the two-letter numeric test 
operators defined in test(l) such as eq, it, and the like. The leading dash (-) should not be included. 

Thefifth field specifies a constant with which to compare the value using the operator just defined. This isdoneby invoking 
the command 

test value -operator constant 

The line is said to "succeed" if it returns true. 

The sixth field specifies what should be done if the line succeeds and in some cases if it fails. Any of the following words may 
be used: 

throttle C auses innwatch to throttle the server if this line succeeds. It also sets the state to the value of 

the line's label. If the line fails and the state was previously equal to the label on this line (that 
is, this line had previously succeeded), then ago command will be sent to the server, and 
innwatch will return to the run state The throttle is only performed if the current state is run 
or a state other than the label of this line, regardless of whether the command succeeds 
pause Is identical to throttle except that the server is paused, 

shutdown Sends a shutdown command to the server. It is for emergency use only, 

flush Sends a flush command to the server. 

go C auses innwatch to send a go command to the server and to set the state to run. 

exit C auses innwatch to exit. 

skip T he result of the control file is skipped for the current pass. 


The last field specifies the reason that is used in those ctiinnd commandsthat require one M ore strictly, it is part of the 
reason; innwatch appends some information to it. In order to enable other sites to recognize the state of the local innd server, 
thisfield should usually beset to one of several standard values. Use no space if the server is rejecting articles because of a 
lack of filesystem resources. U se loadav if the server is rqecting articles because of a lack of C PU resources 
Once innwatch has taken some action as a consequence of its control line it skips the rest of the control file for this pass. If 
theaction was to restart the server (that is issue a go command), then the next pass will commence almost immediately so 
that innwatch can discover any other condition that may mean that the server should be suspended again. 


EXAMPLES 

@@@df .|awk 'NR==2 {print $4}'@lt@10000@throttle@No space 

@@@df -i .|awk 'NR==2 {print $4} 1 01t@1000@throttle0No space (inodes) 

The first line causes the server to be throttled if the free space drops below 10000 units (using whatever units df uses) and 
restarted again when free space increases above thethreshold. 

The second line does the same for inodes. 

The next three lines act as a group and should appear in the following order. It is easier to explain them, however, if they are 
described from the last up. 
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!load!load hiload!loadavg!It!5!go! 

:hiload:+ load:loadavg:gt:8:throttle:loadav 
/load/+/loadavg/ge/6/pause/loadav 

The final line causes the server to be paused if innwatch is in the run state and the load average rises to, or above six. The 
state is set to load when this happens The previous line causes the server to be throttled when innwatch is in the run or load 
state, and the load average rises above eight. The state is set to hiload when this happens Note that innwatch can switch the 
server from paused to throttled if the load average rises from below six to between six and seven and then to above eight. T he 
first line causes the server to be sent a go command if innwatch is in the load or hiload state and the load average drops below 
five. 

Note that all three lines assume a mythical command loadavg that is assumed to print the current load average as an integer. 

In more practical circumstances, a pipe of uptime into awk is more likely to be useful. 

BUGS 

Thisfile must be tailored for each individual site; the sample supplied is truly no more than a sample. The file should be 
ordered so that the more common problems are tested first. 

The run state is not actually identified by the label with that three letter name, and using it will not work as expected. 

Using an "unusual" character for the delimiter such as (, *, &, 11 ", and the like is likely to lead to obscure and hard-to-locate 
bugs. 

HISTORY 

W ritten by (kre@munnan.oz.au) for InterN etN ews. 

SEE ALSO 

inndfSJ, ctlinndfSJ, news.dailyfSJ 

ipc 

ipc- System V interprocess communication mechanisms. 

SYNOPSIS 

# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/msg.h> 

# include <sys/sem.h> 

# include <sys/shm.h> 

DESCRIPTION 

The manual page refers to theLinux implementation of the System V interprocess communication mechanisms message 
queues, semaphore sets, and shared memory segments In the following, the word resource means an instantiation of one 
among such mechanisms. 

RESOURCE ACCESS PERMISSIONS 

For each resource, the system uses a common structure of type struct ipc_perm to store information needed in determining 
permissions to perform an ipc operation. Theipc_perm structure defined by the<sys/ipc.h> system header file, includes the 
following members: 

ushort cuid; /* creator user id */ 
ushort cgid; /* creator group id */ 

ushort gid; /* owner group id */ 
ushort mode; /* r/w permissions */ 







ipc 


The mode member of the ipc_perm structure defines, with its lower nine bits, the access permissions to the resource for a 
process executing an ipc system call. The permissions are interpreted as follows: 


0200 

0040 

0020 


0002 


Read by user. 

W rite by user. 
Read by group. 
W rite by group. 
Read by others 
W rite by others. 


Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. Furthermore "write" effectively means "alter" fora 
semaphore set. 

The same system header file defines also thefollowing symbolic constants: 
ipc_creat Create entry if key doesn't exists. 

ipc_excl Fail if key exists. 

ipc_nowait Error if request must wait. 

ipc_private Private key. 

ipc_rmid Remove resource 

ipc_set Sdt resource options 

ipc_stat G et resource options. 


N ote that ipc_private is a key_t type whereas all the others symbolic constants are flag fields O Rable into an int type 
variable 


MESSAGE QUEUES 

A message queue is uniquely identified by a positive integer (itsmsqid) and has an associated data structure of type struct 
msqutd_ds, defined in <sys/msg.h>, containing thefollowing members 

struct ipc_perm msg_perm; 
ushort msg_qnum; /* no of messages on queue */ 
ushort msg_qbytes; /* bytes max on a queue */ 
ushort msg_lspid; /* pid of last msgsnd call */ 

ushort msg_lrpid; /* pid of last msgrcv call */ 

time_t msg_stime; /* last msgsnd time */ 

time_t msg_rtime; /* last msgrcv time */ 

time_t msg_ctime; /* last change time */ 


msg_perm 

msg_qnum 

msg_qbytes 

msg_lspid 


ipc_perm structure that specifies the access permissions on the message queue. 
N umber of messages currently on the message queue. 

M aximum number of bytes of message text allowed on the message queue. 

ID of the process that performed the last msgsnd system call. 

ID of the process that performed the last msgrcv system call. 

T ime of the last msgsnd system call. 

T ime of the last msgcv system call. 

Time of the last system call that changed a member of themsqid_ds structure. 


SEMAPHORE SETS 

A semaphore set is uniquely identified by a positive integer (its semid) and has an associated data structure of type struct 
semid_ds, defined in <sys/sem.h>, containing thefollowing members: 

struct ipc_perm sem_perm; 
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time_t sem_ctime; /* last change time */ 
ushort sem_nsems; /* count of sems in set */ 

ipc_perm structure that specifies the access permissionson the semaphore set. 

T ime of last semop system call. 

T i me of last semcti system call that changed a member of the above structure or of one 
semaphore belonging to the set. 

Number of semaphores in the set. Each semaphore of the set is referenced by a non-negative 
integer ranging from 0 to sem_nsems-i. 

A semaphore is a data structure of type struct sen containing the following members; 

ushort semval; /* semaphore value */ 

short sempid; /* pid for last operation */ 

ushort semncnt; /* no. of awaiting semval to increase */ 

ushort semzcnt; /* no. of awaiting semval = 0 */ 

semval Semaphore value a non-negative integer. 

sempid ID of the last processthat performed a semaphore operation on this semaphore, 

semncnt N umber of processes suspended awaiting for semval to increase 

semznt N umber of processes suspended awaiting for semval to become zero. 



SHARED MEMORY SEGMENTS 

A shared memory segment is uniquely identified by a positive integer (its shmid) and has an associated data structure of type 
struct shmid_ds, defined in <sys/shm.h>, containingthefollowing members: 


struct ipc_perm shm_perm; 
int shm_segsz; /* size of segment */ 
ushort shm_cpid; /* pid of creator */ 
ushort shm_lpid; /* pid, last operation */ 
short shm_nattch; /* no. of current attaches */ 

time_t shm_atime; /* time of last attach */ 

time_t shm_dtime; /* time of last detach */ 

time_t shm_ctime; /* time of last change */ 


shm_segsz 

shm_cpid 

shm_lpid 


ipc_perm structure that specifies the access permissionson the shared memory segment. 
Size in bytes of the shared memory segment. 

ID of the process that created the shared memory segment. 

ID of the last processthat executed a shmat orshmdt system call. 

N umber of current alive attaches for this shared memory segment. 

Time of the last shmat system call. 

Time of the last shmdt system call. 

Time of the last shmcti system call that changed shmid_ds. 


SEE ALSO 

ftok(3), msgctl(2), msgget(2), msgrcv(2), msgsnd(2), semctl(2), semget(2), semop(2), shmat(2), shmctl(2), shmget(2), shmdt (2) 

Linux 0.99.13,1 November 1993 


issue 


e- Issue identification file. 
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DESCRIPTION 

Thefile /etc/issue is a text file that contains a message or system identification to be printed before the login prompt. It 
may contain various @ch a r and uim sequencesif supported by getty(l). 

FILES 

/etc/issue 

SEE ALSO 

getty(l), motd(5) 

Linux, 24July 1993 


lilo.conf 

mo.conf— Configuration file for LILO. 

DESCRIPTION 

Thisfile, by default /etc/mo.conf, is read by the boot loader installer LILO (seenio(8)). 

It might look as follows 

boot = /dev/hda 
delay = 40 
compact 
vga = normal 
root = /dev/hdal 

image = /zlmage-1.5.99 
label = try 
image = /zlmage-1.0.9 
label = 1.0.9 
image = /tamu/vmlinuz 
label = tamu 
root = /dev/hdb2 
vga = ask 
other = /dev/hda3 
label = dos 
table = /dev/hda 

This configuration file specifies that LILO uses theM aster Boot Record on /dev/hda. (For a discussion of the various ways to 
use LILO and the interaction with other operating systems, see user.tex from the LILO documentation.) 

W hen booting, the boot loader will wait 4 seconds (40 deciseconds) for you to press Shift. If you don't, then thefirst kernel 
image mentioned (/zimage- 1 . 5 . 99 , which you probably installed just 5 minutes ago) will be booted. If you do, the boot 
loader will ask you which image to boot. In case you forgot the possible choices, pressTab (or ? if you haveaU.S. keyboard), 
and you will be presented with a menu. You now have the choice of booting this brand new kernel, an old trusted kernel, or 
a kernel on another root file system (just in case you did something stupid on your usual root) or booting a different 
operating system. There can be up to 16 images mentioned in lilo.conf. 

As can be seen pre/iously, a configuration file starts with a number of global options (the top six lines in the example), 
followed by descriptions of the optionsfor the variousimages An option in an image description will override a global 
option. 
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GLOBAL OPTIONS 


There are many possible keywords The description that follows isalmost literally from user.tex (just slightly abbreviated): 


backup=b a c k u p- file 


compact 


default=name 
delay=t secs 




disktab=d i skt ab-fiIe 

fix-table 


force-backup=backup- f i I e 
ignore-table 
installed ot - sector 




map=map- file 
message=mess 


nowarn 


Copytheoriginal boot sector to backup-file (which may also bea device, such as/dev/nuii) 
instead Of/boot/boot.NNNN. 

sets the name of the device (such asa hard disk partition) that containsthe boot sector. If 
this keyword is omitted, the boot sector is read from (and possibly written to) the device 
that is currently mounted as root. 

T ries to merge read requests for adj acent sectors into a single read request. T hisdrastically 
reducesload time and keeps the map smaller. Using compact isespecially recommended 
when booting from a floppy disk. 

Uses the specified image as the default boot image. If default is omitted, the image 
appearing first in the configuration file is used. 

Specifies the number of tenths of a second the boot loader should wait before booting the 
first image. Thisis useful on systems that immediately boot from the hard disk after 
enabling the keyboard. The boot loader doesn't wait if delay is omitted or is set to zero. 
Defines non-standard parameters for the specified disk. See section "Disk Geometry" of 
user.tex for details 

Specifies the name of the disk parameter table T he map installer looks for /etc/disktab if 
disktab is omitted. The use of disktabs is discouraged. 

Thisallows LI LO to adjust 3-D addressesin partition tables Each partition entry contains a 
3-D (sector/head/cylinder) and a linear address of the first and the last sector of the 
partition. If a partition is not track-aligned and if certain other operating systems (such as 
PC/M S-D 0 S or 0 S/2) are using the same disk, they may change the 3-D address. LI LO 
can store its boot sector only on partitions where both address types correspond. LILO 
readjusts incorrect 3-D start addresses if fix-tabie isset. 

W arning: This does not guarantee that other operating systems may not attempt to reset the 
addresslater. It is also possible that this change has other, unexpected side effects. The 
correct fix isto repartition the drive with a program that does align partitions to tracks 
Also, with some disks (such as some large El DE disks with address translation enabled), 
under some circumstances, it may even be unavoidable to have conflicting partition table 
entries. 

Like backup but overwrite an old backup copy if it exists. 

T ells LILO to ignore corrupt partition tables. 

Install thespecifiedfileasthenew boot sector. If install isomitted, /boot/boot.b is used as 
the default. 

Generate linear sector addresses instead of sector/head/cylinder addresses. Linear addresses 
are translated at runtime and do not depend on disk geometry. Note that boot disks may 
not be portable if linear is used because the BIO S service to determine the disk geometry 
does not work reliably for floppy disks W hen using linear with large disks, / sbin/nio may 
generate references to inaccessible disk areas because 3-D sector addresses are not known 
before boot time 

Enables automatic recording of boot command lines as the defaults for the following boots. 
This way, LILO "locks" on a choice until it is manually overridden. 

Specifies the location of the map file If map isomitted, the file /boot/map is used. 

Specifies a file containing a message that is displayed before the boot prompt. N o message is 
displayed while waiting for a shifting key after printing lilo . In the message, theFF 
character (Ctrl+L) clears the local screen. The size of the message file is limited to 65,535 
bytes. The map file has to be rebuilt if the message fileischanged or moved. 

D i sables warnings about possible future dangers. 



liloxonf 


password=password 
prompt 

restricted 


timeout=tsecs 


verbose=l e v eI 


The per-image option optional applies to all images. 

T he per-image option passwords.. applies to all images. 

Forces entering the boot prompt without expecting any prior key presses U nattended 
reboots are impossible if prompt is set and timeout isn't. 

The per-image option restricted applies to all images. 

Enables control from aserial line The specified serial port isinitialized and the bootloader 
is accepting input from it and from the PC's keyboard. Sending a break on the serial line 
corresponds to pressing a Shift key on the console in order to get the boot loader's 
attention. All boot images should be password-protected if the serial access is less secure 
than access to the console such as if the line is connected to a modem. The parameter string 
hasthefollowing syntax: 

<por t >[,<bps >[<par i t y >[<bit s>] ] ] 

<por t >: The number of the serial port, zero-based. 0 corresponds to COM 1 alias /dev/ttyso, 
and so on. All four ports can be used (if present). <bps>: The baud rate of the serial port. 

The following baud rates are supported: 110,150,300, 600,1200, 2400,4800, and 9600 
bps. Default is2400 bps. 

<par i t y >: T he parity used on the serial line. The boot loader ignores input parity and strips 
theeighth bit. Thefollowing (uppercase or lowercase) characters are used to describe the 
parity: n for no parity, e for even parity, and 0 for odd parity. 

<bi t s >: The number of bits in a character. Only 7 and 8 bits are supported. Default is 8 if 
parity is none and 7 if parity is even or odd. 

If serial isset, the value of delay is automatically raised to 20 . For example seriai= 0 , 2400 ns 
initializes CO M 1 with the default parameters 

Sdtsa timeout (in tenthsof a second) for keyboard input. If no key is pressed for the 
specified time, thefirst image is automatically booted. Similarly, password input isaborted 
if the user is idlefor too long. T he default timeout is infinite. 

T urns on a lot of progress reporting. FI igher numbers give more verbose output. If -v is 
additionally specified on the LI LO command line, the level is increased accordingly. The 
maximum verbosity level iss. 


Additionally, the kernel configuration parameters append, ramdisk, read-only, read-write, root, and vga can be set in the 
global options section. They are used as defaults if they aren't specified in the configuration sections of the respective kernel 
images. 


PER-IMAGE SECTION 

A per-image section starts with either a line 

image=pat hname 

to indicate a file or device containing the boot image of a Linux kernel or a line 

other=pat hname 

to indicate an arbitrary system to boot. 

In theformer case if an image line specifies booting from a device then one has to indicate the range of sectors to be mapped 
using 

In the latter case (booting another system), there arethethree options: 

loaders hai n-1 oader This specifies the chain loader that should be used. By default, /boot/chain.b is used. The 

chain loader must be specified if booting from a device other than thefirst hard or floppy 
disk. 
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This specifies the device that contains the partition table The boot loader will not pass 
partition information to the booted operating system if this variable is omitted. (Some 
operating systems have other meansto determine from which partition they have been 
booted. For example M S-D OS usually stores the geometry of the boot disk or partition in 
its boot sector.) N otethat /sbin/nio must be rerun if a partition table mapped referenced 
with table is modified. 

D o not access the boot sector at map creation time This disables some sanity checks, 
including a partition table check. If the boot sector is on a fixed-format floppy disk device, 
using unsafe avoids the need to put a readable disk into the drive when running the map 
installer, unsafe and table are mutually incompatible 

In both cases, the following options apply: 

iabei=name The boot loader uses the main filename (without its path) of each image specification to 

identify that image. A different name can be used by setting the variable label. 
aiias=name A second name for the same entry can be used by specifying an alias, 

lock (Seepra/iousdescription.) 

optional 0 mit the image if it is not available at map creation time. This is useful to specify test 

kernels that are not always present. 
password=pa s sword Protect the image by a password. 

restricted A password isonly required to boot the image if parameters are specified on thecommand 

line (SUCh as single). 

KERN EL OPTIONS 

If the booted image is a Linux kernel, then one may pass command-line parameters to this kernel. 
append=st ring Appends the options specified to the parameter line passed to the kernel. T his istypically 

used to specify parameters of hardware that can't be entirely autoddtected or for which 
probing may be dangerous. Example: append = "hd=64,32,202". 
i.tterai-s :' i ng Like append but removes all other options (such as setting of the root device). Because vital 

options can be removed unintentionally with literal, this option cannot be set in the 
global options section. 

ramdisk=s i z e This specifies the size of theoptional RAM disk. A valueof zero indicates that no RAM disk 

should be created. If this variable isomitted, the RAM disk size configured into the boot 
image is used. 

read-only This specifies that the root filesystem should bemounted read-only. Typically, the system 

startup procedure remounts the root filesystem read-write later (such as after fscking it), 
read-write This specifies that the root filesystem should bemounted read-write. 

root=r oot - device This specifies the device that should bemounted asroot. If the special namecurrent isused, 

the root device is set to the device on which the root filesystem is currently mounted. If the 
root has been changed with -r, the respective device is used. If the variable root isomitted, 
the root device setting contained in the kernel imageisused. (That is set at com pile time 
using the root dev variable in the kernel makefile and can later be changed with therdev(8) 
program.) 

vga=mode ThisspecifiestheVGA text mode that should beselected when booting. Thefollowing 

values are recognized (case is ignored): 
normal: Select normal 80x25 text mode, 
extended (or ext): Select 80x50 text mode, 
ask: Stop and ask for user input (at boot time). 

<n u mb er>: Use the corresponding text mode. A list of available modes can beobtained by 
booting with vga=ask and pressing Enter. 






moderators 


If this variable isomit±ed, theVGA modesetting contained in thekerne! imageisused. 
(That isset at compiletime using the svga mode variablein the kernel makefileand can later 
be changed with therdev(8) program.) 


SEE ALSO 

nio(8), rdev(8). The LI LO distribution comes with very extensive documentation of which the preceding information is an 
extract. 


28 July 1995 


MAKEDEV.cfg 

MAKEDEv.cfg— Configuration for makedev(8 ). 

DESCRIPTION 

MAKEDEv.cfg isa text filethat tells makedev(8 ) what to do (and equally importantly, what not to do). Unlike devinfo(5), which 
is meant to be centrally maintained, it containsall local configuration for a particular site and all customization. There are 
basically two kinds of declaration in thisfile a "class" declaration and an "omit" declaration. 

A class declaration hastheform 

This says that any devices placed in the specified class by devinfo should be created with this ownership and these permis¬ 
sions. A sample entry might be 
class public: root system 0666 

This says that devices marked public should be owned by root, system and have mode 666 . 

An omit declaration hastheform 

This causes the specified devices to never be created, even if explicitly specified. Use caution when setting this up. The intent 
is to be able to run makedev update and not have it create all sorts of useless devices you'd never use. 

SEE ALSO 

makedev(8), devinfo(5) 

Verson 1.4, January 1995 


moderators 

moderators— M ai I addresses for moderated U senet newsgroups. 

DESCRIPTION 

The GetModeratorAddress(3) routine reads thefile /news/iib/moderators to determine how to reach the moderator of a 
newsgroup. This is used by inews(l) when an unapproved local posting is made to a moderated newsgroup. 

Thefile is read until a match isfound. Blank lines and lines starting with a number sign (#) are ignored. All other lines 
should consist of two fields separated by a colon. 

Thefirst field is a wiidmat(3)-style pattern. If it matches the name of the newsgroup, then the second field istaken to be a 
format string for sprintf (3). This string should have at most one%s parameter, which will be given the name of the 
newsgroup with periods transliterated to dashes 
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Here is a sample file 

too.important:announce■request@foo.com 
foo.*:%s@mailer.foo.com 
gnu.*:%s@prep.ai.mit.edu 
:%s@uunet.uu.net 

Using this file, postings to the moderated newsgroup in the left column will be sent to the address shown in the right 
column: 

f oo. important announce - requests oo. com 
foo.x.announce foo-x-announce@mailer.foo.com 
gnu.emacs.sou roes gnu-emacs-sources@prep.ai.mit.edu 
comp.sources.Unix comp - sources -unix@uunet.uu.net 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

inews(l), inn.conf(5), libinn(3), wildmat(3) 

/etc/modules 

/etc/moduies— Kernel modules to load at boot time. 

DESCRIPTION 

The /etc/moduies file contains the names of kernel modules that are to be loaded at boot time, one per line Comments 
begin with a #, and a/erything on the line after them are ignored. 

Debian GNU/Linux version 0.93 


motd 

motd — M essage of the day. 

DESCRIPTION 

T he contents of /etc/motd are displayed by iogin(l) after a successful login but just before it executes the login shell. 

The motd stands for "message of theday," and this file has been traditionally been used for exactly that. (It requires much less 
disk space than mail to all users) 

FILES 

/etc/motd 

SEE ALSO 

login(l) issue(5) 

Linux, 29 December 1992 


mtools 

mtoois— T able of D 0 S devices 



mtools 


DESCRIPTION 

/etc/mtoois.conf and -/.mtooisrc are the configuration files for mtools. These configuration files describe thefollowing 
items 

Global configuration flags and variables 
Per-driveflags and variables 
C haracter translation tables 

/etc/mtoois.conf isthe system-wide configuration file, and -/.mtooisrc isthe user's private configuration file. 

GENERAL SYNTAX 

The configuration files is made up of sections Each section starts with a keyword identifying the section followed byacolon. 
Then follow variable assignments and flags. Variable assignments take the following form: 


Flags are lonekeywords without an equal sign and vai ue following them. A section either ends at the end of the file or where 
the next section begins. 

Linesstarting with a hash (#) are comments. Newline characters are equivalent to whitespace (except where ending a 
comment). The configuration file iscase insensitive, except for items enclosed in quotes (such as filenames). 

DEFAULT VALUES 

For most platforms, mtools contains reasonable compiled-in defaults. You usually don't need to bother with the configura¬ 
tion file if all you want to do with mtools isaccess your floppy drives 0 n the other hand, the configuration file is needed if 
you also want to usemtoois to access your hard disk partitions and dosemu image files 

GLOBAL VARIABLES 

G lobal variables may be set to i or to 0 . 

Thefollowing global flags are recognized: 

mtools_skip_check If this is set to 1 , mtools skips most of its sanity checks. Thisisneeded to read someAtari 

disks that have been made with the earlier RO M s and that would not be recognized 
otherwise 

mtools_fat_compati bi lity If this is set to i, mtools skips the FAT size checks. Some disks have a bigger FAT than they 
really need. These are rqected ifthisoption is not set. 

mtools_lower_case If this is set to i, mtools displays all-uppercase short filenamesas lowercase Thishasbeen 

doneto allow a behavior that isconsistent with older versionsof mtools, which didn't know 
about the case bits 

For example, inserting thefollowing line into your configuration file instructs mtools to skip thesanity checks 

MT00LS_SKIP_CHECK=1. 

G lobal variables may also be sdt via the environment: export mtools_skip_check=i . 

PER-DRIVE FLAG SAND VARIABLES 

Per-drive flags and values may be described in a drive section. A drive section starts with drive dr i vei etter 
Then follow variable-value pairs and flags 

GENERAL PURPOSE DRIVE VARIABLES 

Thefollowing variables are available: 

tile T he name of thefile or device holding the disk image. T his is mandatory. T he filename 

should be enclosed in quotes 
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use_xdf If this is set to a nonzero value, mtoois also tries to accessthis disk as an Xdf disk. Xdf is a 

high-capacity format used by OS/2. This is off by default. 

partition Tells mtoois to treat the drive as a partitioned device and to use the given partition. Only 

primary partitionsareaccessible using this method, and they are numbered from 1 to 4. For 
logical partitions, use the more general offset variable. The partition variable is intended 
for Syquests, ZIP drives, and DOSE M U hdi mages It is not recommended for hard disks to 
which direct access to partitions is available. 

offset Describes where in the file the M S-D OS filesystem starts. This is useful for logical partitions 

inDOSEMU hdimages and for ATARI RAM disks. By default, this is zero, meaningthat 
the filesystem starts right at the beginning of the device or file 
fatbits The number of FAT bits. Thiscan be 12 or ie. This is very rarely needed because it can 

almost always be deduced from information in the boot sector. 0 n the contrary, describing 
the number of fat bits can actually be harmful if you get it wrong. You should only use it if 
mtoois gets the autoddtected number of fat bits wrong or if you want to mformat a disk with 
a weird number of fat bits 


0 nly the file option is mandatory. T he other parameters may be left out. I n that case, a default value or an autodetected 
value isused. 


DRIVE GEOMETRY CON FIGURATION 

Geometry information describes thephysical ch aracteri sti cs about the disk. Its has three purposes 


mformat 


filtering 


initial geometry 


The geometry information is written into the boot sector of the newly made disk. However, 
you may also describethegeometry information on thecommand line. Seemformat(l)for 
details. 

On some Unices device nodes only support one physical geometry. The geometry is 
compared to the actual geometry stored on the boot sector to make sure that thisdevice 
node is able to correctly read the disk. If the geometry doesn't match, this drive entry fails, 
and the next drive entry bearing the same drive letter is tried. See the next section "Supply¬ 
ing M ultiple D escriptionsfor a D rive" for more details on supplying several descri ptionsfor 
a drive letter. 

If no geometry information is supplied in the configuration file all disks are accepted. On 
Linux (and on Sparc), there exist device nodes with configurable geometry (/dev/fdo, /dev/ 
fdi etc), so filtering is not needed (and ignored) for disk drives (mtoois still does do 
filtering on plain files (disk images) in Linux: T his is mainly intended for test purposes 
because I don't have access to a UN IX that would actually need filtering.) 

Thegeometry information (if available) is also used to set the initial geometry on 
configurable device nodes This initial geometry isused to read the boot sector, which 
containsthereal geometry. If no geometry information issupplied in the configuration file, 
no initial configuration isdone On Linux, thisisnot really needed either because the 
configurable devices are able to autodetect the disk type accurately enough (for most 
common formats) to read the boot sector. 


W rang geometry information may lead to very bizarre errors. T hat's why I strongly recommend that you don't use geometry 
configuration unless you really need it. 

Thefollowing geometry related variables are available: 
cylinders Thenumberof cylinders, 

heads Thenumber of heads(sides). 

sectors The number of sectors per track. 
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For example, thefollowing drivesection describesa 1.44M drive: 

file="/dev/fd0H1440" 
fat_bits=12 

tracks=80 heads=2 sectors=18 

Thefollowing shorthand geometry descriptions are available 

1.44M H igh density, 3 1/2 disk. Equivalent to fat_bits=i 2 tracks =80 heads =2 sectors=i8. 

1.2M FI igh density, 5 1/4 disk. Equivalent to fat_bits=i 2 tracks =80 heads =2 sectors=i5. 

720K Double density, 3 1/2 disk. Equivalent to fat_bits=i 2 tracks =80 heads =2 sectors=9. 

360K Double density, 5 1/4 disk. Equivalent to fat_bits=i 2 tracks=40 heads =2 sectors=9. 

The shorthand format descriptions may be amended. For example, 360K sectors=8 describesa 320K disk and isequivalent to 

fat_bits=12 tracks=40 heads=2 sectors=8. 

OPEN FLAGS 

M oreover, the following flags are available: 

sync All I/O operations are done synchronously. 

nodeiay The device orfileis opened with the o_ndelay flag. Thisisneeded on some non-Linux 

architectures 

exclusive The device orfileis opened with theo_ExcL flag. On Linux, thisensuresexdusiveaccessto 

thefloppy drive. On most other architectures and for plain files it has no effect at all. 

SUPPLYING MULTIPLEDESCRIPTIONSFORA DRIVE 

It ispossibleto supply multiple descriptionsfor a drive In that case the descriptions are tried in order until oneisfound 
that fits D escriptionsmay fail for several reasons 

■ The geometry is not appropriate 

■ Thereisnodiskinthedrive 

■ Other problems 

M ultiple definitions are useful when using physical devices that are only able to support one single disk geometry: 

drive a: file="/dev/fd0H1440" 1.44m 
drive a: file="/dev/fd0H720" 720k 

This instructs mtools to use/dev/fdOHi440 for 1.44M (high density) disks and /dev/fd0H72@for72OK (double density) disks. 
On Linux, thisfeature is not really needed because the/dev/fdo device is able to handle any geometry. 

You can also use multiple drive descriptionsto access both of your physical drives through one drive letter: 
drive z: file="/dev/fd0" 
drive z: file="/dev/fdl" 

With this description, mdir z: accesses your first physical drive if it contains a disk. If the first drive doesn't contain a disk, 
mtools checks the second drive. 

When using multiple configuration files, drive descriptions in the files parsed last override descriptionsfor the same drivein 
earlier files In order to avoid this, usethedrive+ or+drive keywords instead of drive. The first adds a description to the end 
of the list (will be tried last), and the second adds it to the start of the list. 

CHARACTER TRANSLATION TABLES 

If you live in the USA, in Western Europe or in Australia, you can skip thissection. 



PartV: File Formats 


INTRODUCTION 

DO S uses a different character code mapping from UN IX. Sa/en-bit characters still have the same meaning; only characters 
with the eight-bit set are affected. To make matters worse, there are several translation tables available depending on the 
country where you are T he appearance of the characters is defined using code pages. These code pages aren’t the same for all 
countries For instance, some code pages don't contain upper-case accented characters On the other hand, some code pages 
contain characters that don't exist in UN IX, such ascertain line-drawing characters or accented consonants used by some 
Eastern European countries This affects two things relating to filenames 

Uppercase characters In short names, only uppercase characters are allowed. This also holdsfor accented 

characters. For instance in a code page that doesn't contain accented uppercase characters 
the accented lowercase characters get transformed into their unaccented counterparts 
Long filenames M icrosoft has finally come to their senses and uses a more standard mapping for the long 

filenames They use Unicode which is basically a 32-bit version of ASCII. Its first 256 
characters are identical to U NIX ASC11. T hus, the code page also affects the correspondence 
between the codes used in long names and those used in short names 

mtoois considers thefilenames entered on thecommand line as having the UN IX mapping and translates the characters to 
get short names. By default, code page 850 is used with the Swiss uppercas^lowercase mapping. I chose this code page 
because its set of existing characters most closely matches U NI X's M oreover, this code page covers most characters in use in 
the USA, Australia, and Western Europe. FI owever, it isstill possible to chose a different mapping. There are two methods 
the country variable and explicit tables 

CONFIGURATION USING COUNTRY 

The country variable is recommended for people that also have access to MS-DOS system files and documentation. If you 
don't have access to these I’d suggest you use explicit tables instead. 

Syntax: COUNTRY=" country [,[ codepage ], country.sys ]" 

This tells mtoois to use a UN IX-to-DOS translation table that matchescodepage and an I owercase-to-uppercase table for 
c o u n t r y and to use the c o u n t r y. s y s file to get the lowercase-to-uppercase table. The country code is most often the telephone 
prefix of the country. Refer to the D 0 S help page on country for more details. T he c o d e p a g e and the c o u nt r y. s y s parameters 
are optional. Don't type in the square brackets; they are only there to indicate which parameters are optional. The 
country, sys file issupplied with M S-DOS. In most cases, you don't need it because the most common translation tables are 
compiled into mtoois. Don't worry if you run aUN IX-only box that lacks thisfile 

If codepage is not given, a per-country default code page is used. If thecount r y. s ys parameter isn't given, compiled-in 
defaults are used for the lowercase-to-uppercase table. This is useful for other Unices than Linux, which may have no 
country, sys file available online. 

The UN IX-to-DOS are not contained in thecount ry. sys file and thus mtoois always uses compiled-in defaultsfor those 
Thus, only a limited amount of code pages are supported. If your preferred code page is missing, or if you know the name of 
the Windows 95 file that contains this mapping, drop mealineatAiain.Knaff@inriaipes.fr. 

The country variablecan also beset using the environment. 

CONFIGURATION USING EXPLICIT TRANSLATION TABLES 

T ranslation tables may be described in lines in the configuration file. Two tables are needed: first the DOS-to-UN IX table 
and then the lowercase-to-uppercase table A DOS-to-UN IX table starts with thetounix keyword, followed by acolon and 
128 hexadecimal numbers. A lower-to-upper table starts with thefucase keyword, followed by a colon and 128 hexadecimal 
numbers. 

Thetablesonlyshowthetranslationsfor characters whose codes is greater than 128 because translation for lower codesis 
trivial. Example: 
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0xc7 0xfc 0xe9 0xe2 0xe4 0xe0 0xe5 0xe7 
0xea 0xeb 0xe8 0xef 0xee 0xec 0xc4 0xc5 
0xc9 0xe6 0xc6 0xf4 0xf6 0xf2 0xfb 0xf9 
0xff 0xd6 0xdc 0xf8 0xa3 0xd8 0xd7 0x5f 
0xe1 0xed 0xf3 0xfa 0xf1 0xd1 0xaa 0xba 
0 xbf 0xae 0xac 0xbd 0xbc 0xa1 0xab 0xbb 
0x5f 0x5f 0x5f 0x5f 0x5f 0xc1 0xc2 0xc0 
0xa9 0x5f 0x5f 0x5f 0x5f 0xa2 0xa5 0xac 
0x5f 0x5f 0x5f 0x5f 0x5f 0x5f 0xe3 0xc3 
0x5f 0x5f 0x5f 0x5f 0x5f 0x5f 0x5f 0xa4 
0xf0 0xd0 0xc9 0xcb 0xc8 0x69 0xcd 0xce 
0xcf 0x5f 0x5f 0x5f 0x5f 0x7c 0x49 0x5f 
0xd3 0xdf 0xd4 0xd2 0xf5 0xd5 0xb5 0xfe 
0xde 0xda 0xd9 0xfd 0xdd 0xde 0xaf 0xb4 
0xad 0xb1 0x5f 0xbe 0xb6 0xa7 0xf7 0xb8 
0xb0 0xa8 0xb7 0xb9 0xb3 0xb2 0x5f 0x5f 





The first table maps DOS character codes to UN IX character codes. For example the D 0 S character number 129 isau with 
two dots on top of it. T o translate it into U NIX, we look at the character number 1 in the first table (1 =129 - 128). This is 
0 xf c. (Beware; numbering starts at 0.) T he second table maps lowercase DOS characters to uppercase DOS characters T he 
same lowercase u with dots maps to character 0 x 9 a, which is an uppercase U with dots in DOS. 


UNICODE CHARACTERS GREATER THAN 256 

If an existing MS-DOS name contains U nicode character greater than 256, these are translated to underscores or to 
characters that are close in visual appearance. For example, accented consonants are translated into their unaccented 
counterparts This translation is used for mdir and for the UN IX filenames generated by mcopy. Linux does support Unicode 
too, but unfortunately, too few applications support it yet to bother with it in mtools. M ost importantly, xterm can't display 
Unicode yet. If there is sufficient demand, I might include support for Unicodein the UN IX filenames as well. 

Caution: When deleting files with mtools, the underscore matches all characters that can't be represented in UN IX. Be 
careful before mdei I 


LOCATION OF CON FIGURATION FILES AND PARSING ORDER 

The configuration files are parsed in the following order: 
Compiled-in defaults 






























PartV: File Formats 


/etc/mtools.conf 

/etc/mtoois. This is for backwards compatibility only and is only parsed if mtoois.conf doesn't exist. 

-/.mtoolsrc 

Options described in the later files override those described in the earlier files Drives defined in earlier files persist if they are 
not overridden in the later files For instance, drives A and B may be defined in /etc/mtoois.conf anddrivesC and D maybe 
defined in -/.mtoolsrc. H owever, if -/.mtoolsrc also definesdriveA, thisnew description would override the description of 
driveA in /etc/mtoois.conf instead of adding to it. If you want to add a new description to a drive already described in an 
earlier file, you need to use either the +drive ordrive+ keywords 

BACKWARDS COMPATIBILITY 

The syntax described herein is new for version mtoois 2.5.4. The old line-oriented syntax is still supported. Each line 
beginning with a single letter isconsidered to be a drive description using the old syntax. Old style and new style drive 
sections may be mixed within the same configuration file to make upgrading easier. Support for the old syntax will be phased 
out eventually, and to discourage its use I purposefully omit its description here. 

FILES 

/etc/mtools.conf 


SEE ALSO 

mtools(l) 
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newsfeeds 

newsfeeds— D etermine where U senet articles get sent. 

DESCRIPTION 

Thefile /news/iib/newsfeeds specifies how incoming articles should be distributed to other sites. It is parsed by the 
I nterN etN ews server innd(8) when it starts up or when directed to by ctiinnd(8). 

Thefile is interpreted as a set of lines according to the following rules. If a line ends with a backslash, then the backslash, the 
newline and any whitespace at the start of the next line isdeleted. This is repeated until the entire "logical" line is collected. 
If the logical line is blank or starts with a number sign (#), it is ignored. 

All other lines are interpreted as feed entries. An entry should consist of four colon-separated fields; two of the fields may 
have optional subfields, marked off by a slash. Fields or subfields that take multiple parameters should be separated by a 
comma. Extra whitespace can cause problems Except for the site names case is significant. The format of an entry is 

si tename [/exclude, exclude, ...]\ 

:pattern, pattern ...[/distrib.di strib — ]\ 

:flag,f I ag...\ 

Each field is described below. 

The si tename is the name of the site to which a news article can be sent. It is used for writing log entries and for determining 
if an article should be forwarded to a site. If si tename already appears in the article's Path header, then the article will not be 
sent to the site. T he name is usually whatever the remote site uses to identify itself in the Path line but can be almost any 
word that makes sense; special local entries (such as archivers or gateways) should probably end with an exclamation point to 
make sure that they do not have the same name as any real site. For example, gateway is an obvious name for the local entry 
that forwards articles out to a mailing list. If a site with the name gateway posts an article when the local site receives the 
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article it will see the name in the Path and not send the article to its own gateway entry. If an entry has an exclusion subfield, 
then the article will not be sent to that site if any of the names specified as excludes appear in the Path header. The same 
sitenamecan be used more than once; the appropriate action will betaken for each site that should receive the article, 
regardless of the name, although this is recommended only for program feeds to avoid confusion. C ase is not significant in 
site names. 

The pat terns specify which groups to send to thesiteand are interpreted to build a "subscription list" for the site. The 
default subscription is to get all groups The patterns in thefield are wiidmat(3)-style patterns and are matched in order 
against the list of newsgroups that the local site receives. If thefirst character of a pattern is an exclamation mark, then any 
groups matching the pattern are removed from the subscription; otherwise any matching groups are added. For example to 
receive all comp groups but only comp, sources, unix within the sources newsgroups, thefollowing si of patterns can be used: 
comp.*,!comp.sources.*,comp.sources.Unix 

There are three things to note about this example. Thefirst isthat the trailing .* is required. The second is that, again, the 
result of the last match is the most important. The third isthat comp, sources.* could be written as comp, sources*, but this 
would not have the same effect if there were a comp, sources ■ only group. 

See innd(8) for details on the propagation of control messages 

A subscription can be further modified by specifying "distributions" that the site should or should not receive. The default is 
to send all articles to all sites that subscribe to any of the groups where it has been posted, but if an article has a Distribution 
header and any distribs are specified, then they are checked according to thefollowing rules: 
t. If the D istribution header matches any of the values in the subfield, then the article is sent. 

2. If adistrib starts with an exclamation point and it matches the Distribution header, then the article is not sent. 

3. If Distribution header does not match any distrib in the site's entry and no negations were used, then the article is not 
sent. 

4. If D istribution header does not match any distrib in the site's entry and any distrib started with an exclamation point, 
thentheartideissent. 

If an article has more than one distribution specified, then each one is evaluated according to the preceding rules. If any of 
the specified distributions indicate that the article should be sent, it is. If none do, it is not sent: The rules are used as a 
"logical or." It isalmost definitely a mistake to havea singlefeed that specifies distributionsthat start with an exclamation 
point along with some that don't. 

Distributions are text words, not patterns; it is usually a mistake to have entries like* or an there 
T he f i a g s parameter specifies miscellaneous parameters. T hey may be specified in any order; flags that take values should 
have the value immediately after theflag letter with no whitespace. The valid flags are 

< size An article will only be sent to the site if it is less than size bytes long. The default is no 

limit. 

a checks An article will only be sent to the site if it meets the requirements specified in the checks, 

which should be chosen from thefollowing set: 
d Distribution header required 

p D o not check Path header before propagating. 

b hi gh/i ow If a site is being fed by a file, channel, or exploder, the server will usually start trying to write 

the information as soon as possible Providing a buffer may give better system performance 
and help smooth out overall load if a large batch of news comes in. The value of the this flag 
should be two numbersseparated by a slash. Thefirst specifies the point at which the server 
can start draining the feed's I/O buffer, and thesecond specifies when to stop writing and 
begin buffering again; the units are bytes. The default isto do no buffering, sending output 
as soon as it is possible to do so. 

f name T his flag specifies the name of the file that should beused if it is necessary to begin spooling 

for the site. If nameisnot an absolute pathname, it is taken to be relative to /news/spooi/ 
out.going. Then, if the destination is a directory, thefileto go in that directory will beused 
as filename 
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If this flag is specified, an article will only be sent to the site if it is posted to no more than 
count newsgroups. 

If thisflag isspecified, an article will only besent to thesite if it hascount or fewer sites in 
its Path line. Thisflag should only be used as a rough guide because of the loose interpreta¬ 
tion of the Path header; some sites put the poster's name in the header, and some sites that 
might logically be considered to be one hop becometwo because they put the posting 
workstation's name in the header. The default value for count is one 
Theflag specifies the size of the internal buffer for a file feed. If there are more file feeds 
than allowed by the system, they will be buffered internally in least recently used order. If 
the internal buffer grows bigger than s i z e bytes, however, the data will be written out to the 
appropriate file 

The newsgroups that a site receives are modified according to the modifiers, which should 
be chosen from the following set: 
m Only moderated groups 

u 0 nly unmoderated groups 

If the amount of data queued for the site gets to belarger than size bytes, then theserver 
will switch to spooling, appending to a file specified by the f flag or /news/spooi/out.going/ 
s i t e n a me if the f flag is not specified. Spooling usually happens only for channel or exploder 
feeds. 

T his flag specifies the type of feed for the site type should bea letter chosen from the 
following set; 
c Channel 

f File 

1 Log entry only 

m Funnel (multiple entries feed into one) 

p Program 

x Exploder. Each feed isdescribed in the section on feed types. 

T he default is Tt. 

If a site is fed by file channel, or exploder, thisflag controls what information is written. If 
a si te i s fed by a program, only theasterisk (*) has any effect. The items should be chosen 
from the following set: 
b Size of the article in bytes 

f Artide'sfull pathname. 

g The newsgroup the article is in; if cross-posted, then the first of the groups 

this site gets 

m Article's Message-1 D. 

n Article's pathname relative to the spool directory, 

p T he site that fed the arti de to the server; from the Path header, 

s The IP address of the site that sent the article 

t Time article was received assecondssinceepoch. 

* Names of the appropriate funnel entries; or all sites that get the article 

d Value of the Distribution header; ? if none present. 

h All headers 

n Value of the Newsgroups header, 

o Overviewdata. 

r Information needed for replication. M ore than one letter can be used; the 

entries will be separated by a space and written in the order in which they are 
specified. The default iswn. 
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T he h and o items are i ntended for use by programs that create news overvi ew databases. I f h 
is present, then the all the article's headers are written followed by a blank line. An Xref 
header (even if one does not appear in the filed article) and a Bytes header, specifying the 
article's size, will also be part of the headers If used, this should be the only item in the list; 
if preceded by other items however, a newline will be written before the headers. The o 
generates input to theoverchan(8) program. It, too, should be the only item in the list. 

The asterisk has special meaning. It expands to a space-separated list of all sites that received 
the current article. If the site is the target of a funnel, however (that is, it is named by other 
sites that have a Tm flag), then the asterisk expands to the names of the funnel feeds that 
received the article. If the site is fed by a program, then an asterisk in the param field will be 
expanded into the list of funnel feeds that received the article. A site fed by a program 
cannot get the site list unless it is the target of other Tm feeds. 

The interpretation of the pa ram field depends on the type of feed, and is explained in more detail in the section on feed types. 
It can be omitted. 

The site named me is special. There should only be one such entry, and it should be the first entry in the file. If the me entry 
has a subscription list, then that list is automatically prepended to the subscription list of all other entries For example, 

*, i control,! junk, itoo.* can be used to set up the initial subscription list for all feedsso that local postings are not propa¬ 
gated unless too.* explicitly appears in the site's subscription list. Note that most subscriptions should haver junk,! control 
in their pattern list; see the discussion of control messages in innd(8). (Unlike other news software, it does not affect what 
groups are received; that is done by the active(5) file.) 

If the me entry has a distribution subfield, then only articles that match thedistri bution list are accepted; all other articles are 
rqected. A commercial news server, for example, might have /r local to rqect local postingsfrom other, misconfigured, sites 

FEED TYPES 

innd provides four basic types of feeds: log, file, program, and channel. An exploder is a special type of channel. In addition, 
several entries can feed into the same feed; these are funnel feeds, which refer to an entry that is one of the other types. N ote 
that the term "feed" is technically a misnomer because the server does not transfer articles but reports that an article should 
besenttothesite. 

The simplest feed is one that is fed by a log entry. Other than a mention in the news logfile, no data isever written out. This 
isequi valent to a Tf entry writing to /dev/nuii except that no file isopened. 

A site fed by a file is simplest type of feed. When the site should receive an article one line is written to thefilenamed by the 
par am field. If param is not an absolute pathname, it is taken to be relative to /news/spooi/out. going. If empty, the filename 
defaults to /news/spooi/out.going/si t ename . T his nameshould beunique 

When a si te fed by a file is flushed (seectunnd), the following steps are performed. The script doing the flush should have 
first renamed the file. The server tries to write out any buffered data and then closes the file. The renamed file is now 
available for use. Theserverwill then reopen the original file, which will now get created. 

A site fed by a program has a process spawned for every article that the site receives The par am field must beasprintf(3) 
format string that may have a single %s parameter, which will be given a pathname for the article, relative to the news spool 
directory. The full pathname may be obtained by prefixing the%s in the par am field by the news spool directory prefix. 
Standard input will be set to the article or /dev/nuii if the article cannot be opened for some reason. Standard output and 
error will be set to the error log. The process will run with the user and group ID ofthe/news/iib/innd directory, innd will 
try to avoid spawning a shell if the command hasno shell meta-characters; thisfeaturecan be defeated by appending a 
semicolon to the end of the command. Thefull pathname of the program to be run must be specified; for security, path is 
not searched. 

If the entry is the target of a funnel, and if thew* flag is used, then a single asterisk may be used in thepar am field where it 
will be replaced by the names of the sites that fed into the funnel. If the entry is not a funnel, or if thew* flag is not used, 
then the asterisk hasno special meaning. 
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Flushing a sitefed by a program does no action. 

When a site is fed by a channel or exploder, the pa ram field names the process to start. Again, thefull pathname of the process 
must be given. When thesite isto receive an article, the process receivesa line on its standard input telling it about the 
article Standard output and error and the user and group ID of the all subprocess are set as for a program feed. If the process 
exits, it will be restarted. If the process cannot be started, the server will spool input to a file named /news/spooi/out.going/ 
si t e n a me . It will then try to start the process some time later. 

W hen a sitefed by a channel or exploder isflushed, the server closes down its end of the pipe. Any pending data that has not 
been written will be spooled; see the description of the s flag. No signal is sent; it is up to the program to notice EOF on its 
standard input and exit. The server then starts a new process 

Exploders are a superset of channel feeds. In addition to channel behavior, exploders can be sent command lines These lines 
start with an exclamation point, and their interpretation is up to the exploder. The following messages are generated 
automatically by the server: 

newgroup group 
rmgroup group 
flush 
flush site 

T hese messages are sent when the ctiinnd command of the same name is received by the server. I n addition, the send 
command can be used to send an arbitrary command line to the exploder child-process The primary exploder is buff chan(8). 
Funnel feeds provide a way of merging several site entries into a single output stream. For a site feeding into a funnel, the 
par am field names the actual entry that does thefeeding. 

For moredetailson setting up different types of news feeds, seethe IN N installation manual. 

EXAMPLES 

## Initial subscription list and our distributions. 

ME:*,'junk,!foo.*/world,usa,na,ne,foo,ddn,gnu,inet\ 

## Feed all moderated source postings to an archiver 
source-archive!:!*,comp.sources.*\ 

:Tp,Nm:/usr/local/bin/archive %s 
## Watch for big postings 
watcher!:*\ 

:Tc,Wbnm\ 

:exec awk '$1 > 1000000 { print "BIG", $2, $3 }' >/dev/console 

## A UUCP feed, where we try to keep the "batching" between 4 and IK. 

ihnp4:/world,usa.na,ddn,gnu\ 

: Tf, Wf b, B409 6 /1024: 

## Usenet as mail; note ! in funnel name to avoid Path conflicts. 

## Can't use ! in "fred" since it would like look a UUCP address, 
fred:!*,comp.sources.Unix,comp.sources.bugs\ 

barney@bar.com:!*,news.software.nntp,comp.sources.bugs\ 

:Tm:mailer! 
mailer!:!*\ 

:W*,Tp:/usr/ucb/Mail -s "News article" * 

## NNTP feeds fed off-line via nntpsend or equivalent, 
feedl::Tf,Wnm:feed1.domain.name 

## Real-time transmission. 

mit.edu:/world,usa,na,ne,ddn,gnu,inet\ 

:Tc,Wnm:/nntplink -i stdin mit.edu 

## Two sites feeding into a hypothetical NNTP fan-out program: 

:Tm:nntpfunnel1 
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uunet.uu.net/uunet:!ne.*/world,usa,na,too,ddn,gnu,inet\ 

:Tm:nntpfunnel1 
nntpfunnell:!*\ 

:Tc,Wmn*:/nntpfanout 

## A UUCP site that wants comp,* and moderated soc groups 
uucpsite!comp:!*,comp.‘/world,usa,na,gnu\ 

:Tm:uucpsite 

uucpsite!soc:!*,soc.‘/world,usa,na,gnu\ 

:Tm,Nm:uucpsite 

:Tf,Wfb:/usr/spool/batch/uucpsite 

The last two sets of entries show how funnel feeds can be used. For example thenntpfanout program would receive lines like 
thefollowingon its standard input: 

<123@litchi.foo.com> comp/sources/unix/888 nic.near.net uunet.uu.net 
<124@litchi.foo.com> ne/general/1003 nlc.near.net 

BecausetheUUCP funnel isonly destined for one site the asterisk is not needed and entries like the following will be 
written into thefile: 

<qwe#37x@snark.uu.net>comp/society/folklore/3 
<123@litchi.foo.com> comp/sources/unix/888 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

actlve(5), buffchan(8), ctlinnd(8), innd(8), wildmat(3) 

newslog 

newsiog— D escription of U sendt log files 

DESCRIPTION 

M ost log files created by Usenet programs reside in the/var/iog/news directory and have a .log extension. Several versions 
are usually kept with an additional extension such as .i, .2, and so on; the higher the number, the older the log. The older 
versions are compressed. 

The scaniogs script and related utilities (see newsiog{8)) are responsiblefor rotating and compressing these files 
Some log files always have data, others only have data if there is a problem, and others are only created if a particular 
program is used or configuration parameter isset. Theinnstat script (see newsiog(8)) monitors the size of all log files 
Thefollowing files will only accumulate data under the direction of control.cti(5): 
control.log, miscctl.log, newgroup.log, rmgroup.log, unwanted.log 

In order to create these files the message and action fields of control, cti should be chosen from the following table: 

M esage Action M eaning 

an iog=misccti Log all messages by default 

default iog=misccti Log unknown messages 

C reate group and log message 
Log message 


newgroup 

newgroup 


doit=newgroup 

log=newgroup 


continues 
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Message 

Action 

M eaning 

rmgroup 

doit=rmgroup 

Remove group and log message 

rmgroup 

log=rmgroup 

Log message 

"other" 

doit=miscctl 

Log and process the message 

"other" 

log=miscctl 

Log message 


H ere, "other" refers to any other control message such as: 

checkgroups ihave sendme sendsys senduuname version 


Thefollowing isa list of log files 


control.log 




expire.log 


newgroup.log 


nntpsend.log 

rmgroup.log 

unwanted.log 


T his file maintains a count of the number of newgroup and rmgroup control messages seen for 
each newsgroup. The count is of the number of control messages with identical arguments 
regardless of whether they were actually processed. All control arguments, including invalid 
ones, are counted. This file is updated by tally, control, which is invoked by scaniogs if 
either the newgroup or rmgroup logs exist. This file is not rotated. 

This file contains the standard output and standard error of any program spawned by 
innd(8). The most common programs are the control-message handlers found in /news/bin/ 
control. This file should be empty. Scaniogs will print the entire contents of this log file if it 
is non-empty. 

By default, when news.daily isgoingto expire old news articles, it writes the date to this 
file, followed by any output from expire(8) and the ending date All lines but the first are 
indented four spaces 

When control.cti isconfigured asdescribed above all control messages except newgroup 
and rmgroup are appended to thisfile by writeiog. There will be a summary line describing 
the message and the action taken, followed by the article indented by four spaces and a 
blank line. 

When control.cti isconfigured asdescribed above all newgroup messages are appended to 
thisfile using the same format as for misccti.log. 

This file logs articles received by innd. scaniogs summarizes the rqected articles reported in 
thisfile 

All critical error messages issued by innd are appended to thisfile via sysiog(3). T hislog file 
should be empty, scaniogs will print theentire contents of this log file if it is non-empty. 
You should have the following line in your sysiog.cont(5) file: 
news.crit /var/log/news/news.crlt 

All major error messages issued by innd are appended to thisfile via sysiog. This log file 
should be empty, scaniogs will print theentire contents of this log file if it is non-empty. 
You should have the following linein your sysiog.conf file: 

news.err /var/log/news/news.err 

All standard error messages and status messages issued by innd are appended to thisfile via 
sysiog. scaniogs usestheawk(l) script inniog.awk to summarize thisfile You should have 
thefollowing line in your sysiog.conf file: 

The nntpsend(8) programs appends all status messages to thisfile. 

When control.cti isconfigured asdescribed previously, all rmgroup messages are appended 
to thisfile using the same format as for misccti. log. 

This log maintains a count of the number of articles that were rejected because they were 
posted to newsgroups that do not exist at the local site Thisfile is updated by 
tally.unwanted and maintained in reverse numeric order (the most popular rqected group 
first). Thisfile is not rotated. 



nfs 


HISTORY 

Written by Landon Curt Noll (chongo@toad.com) and Rich $alz (rsaiz@uunet.uu.net) for I nterN etN ews. 

SEE ALSO 

control.ctl(5J, ctlinndfSJ, expire®, inndfSJ, news.daily®, nntpsend®, newslog® 


nfs 

nfs- NFS fstab format and options 

SYNOPSIS 

/etc/fstab 

DESCRIPTION 

Thetstab file contains information about which filesystems to mount where and with what options For N FS mounts, it 
containsthe server name and exported server directory to mount from, the local directory that is the mount point, and the 
N FS-specific options that control the way the filesystem is mounted. H ere is an example from an /etc/fstab file from an 
NFS mount. 

server:/usr/local/pub /pub nfs rsize=8192,wsize=8192,timeo=14,intr 

OPTIONS 

rsize=n The number of bytes N FS uses when reading files from an NFS server. The default value is 

dependent on the kernel, currently 1024 bytes. (FI owever, throughput is improved greatly by 
asking for rsize=8i92.) 

wsize=n T he number of bytes N FS uses when writing files to an N FS server. The default value is 

dependent on the kernel, currently 1024 bytes. (FI owever, throughput is improved greatly by 
asking for wsize=8i92.) 

timeo=n Thevaluein tenths of a second beforesending thefirst retransmission after an RPC time¬ 

out. The default value is 7 tenths of a second. After thefirst time-out, the time-out is 
doubled after each successive time-out until a maximum time-out of 60 seconds is reached 
or the enough retransmissions have occurred to cause a major time-out. Then, if the 
filesystem is hard mounted, each new time-out cascade restarts at twice theinitial value of 
the previous cascade again doubling at each retransmission. The maximum timeout is 
always 60 seconds Better overall performance may be achieved by increasing the timeout 
when mounting on a busy network, to a slow server, or through several routersor gateways 
retrans=n T he number of minor timeouts and retransmissions that must occur before a major time 

out occurs. The default is 3 timeouts. W hen a major timeout occurs the file operation is 
either aborted or a "server not responding" message is printed on the console. 
acregmin=n T he minimum time in seconds that attributes of a regular file should be cached before 

requesting fresh information from a server. The default is 3 seconds. 
acregmax=n The maximum time in seconds that attributes of a regular file can becached before 

requesting fresh information from a server. The default is 60 seconds 
acdirmin=n The minimum time in seconds that attributes of a directory should be cached before 

requesting fresh information from a server. The default is 30 seconds 
acdirmax=n The maximum time in seconds that attributes of a directory can becached before requesting 

fresh information from a server. T he default is 60 seconds 

Using actimeo Sftsall of acregmin, acregmax, acdirmin, and acdiraax to the Same Value. There 
is no default value 


actimeo=n 
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namlen=n 




mountport=n 

mounthost=name 

mountprog=n 


mountvers=n 


nfsprog=n 


nfsvers=n 

bg 

fg 








FILES 


The number of times to retry a backgrounded N FS mount operation before giving up. The 
default value is 10000 times. 

When an NFS server does not support version 2 of the RPC mount protocol, this option 
can be used to specify the maximum length of a filename that is supported on the remote 
filesystem. This is used to support the PO SIX pathconf functions. The default is255 
characters. 

The numeric value of the port to connect to theN FS server on. If the port number iso (the 
default) then query the remote host's port mapper for the port number to use If the remote 
host's N FS daemon is not registered with its port mapper, the standard N FS port number 
2049 is used instead. 

The numeric value of the mountd port. 

The name of the host running mountd. 

U se an alternate RPC program number to contact the mount daemon on the remote host. 
Thisoption is useful for hosts that can run multipleNFSservers.Thedefaultvalueis 
100005, which isthe standard RPC mount daemon program number. 

U se an alternate RPC version number to contact the mount daemon on the remote host. 
Thisoption is useful for hosts that can run multiple N FS servers. The default value is 
version 1. 

Use an alternate RPC program number to contact the N FS daemon on the remote host. 
Thisoption is useful for hosts that can run multiple N FS servers. The default value is 
100003, which isthe standard RPC N FS daemon program number. 

U se an alternate RPC version number to contact the N FS daemon on the remote host. T his 
option is useful for hosts that can run multiple N FS servers. The default value is version 2. 

If the first N FS mount attempt times out, continue trying the mount in the background. 
The default is to not to background the mount on time-out but to fail. 

If the first N FS mount attempt times out, fail immediately. This isthe default. 

If an N FS file operation hasa major time-out, then report an I/O error to the calling 
program. The default is to continue retrying N FS file operations indefinitely. 

If an N FS file operation hasa major time-out, then report "server not responding" on the 
console and continue retrying indefinitely. This is the default. 

If an N FS file operation hasa major time-out and it is hard mounted, then allow signals to 
interrupt the file operation and cause it to return eintr to the calling program. The default 
is to notallow file operations to be interrupted. 

M ount the N FS filesystem using POSIX semantics This allows an N FS filesystem to 
properly support the PO SIX pathconf command by querying the mount server for the 
maximum length of a filename T 0 do this, the remote host must support version 2 of the 
RPC mount protocol. M any N FS servers support only version 1. 

Suppress the retrieval of new attributes when creating a file. 

D isable all forms of attribute caching entirely. T hisextractsa server performance penalty, 
but it allows two different N FS clients to get reasonably good results when both clients are 
actively writing to a common filesystem on the server. 

M ount theN FS filesystem using the TCP protocol instead of the default U D P protocol. 

M any N FS severs only support U D P. 

M ount the N FS filesystem using theUDP protocol.Thisisthe default. All the non-value 
options have corresponding nooption forms. For example, nointr means don't allow file 
operations to be interrupted. 


/etc/fstab 



nnrp.access 


SEE ALSO 

fstab(5), mount(8), umount(8), exports(5) 

AUTHOR 

Rick Sladkey (jrs@world.std.com) 

BUGS 

The bg, fg, retry, posix, and nocto options are parsed by mount but currently are silently ignored. The top and namien 
options are implemented but are not currently supported by the Linux kernel. Theumount command should notify the server 
when an N FS filesystem is unmounted. 

Linux 0.99, 20 N member 1993 


nnrp.access 

nnrp.access— Access file for on-campus N N TP sites 

DESCRIPTION 

Thefile/news/iib/nnrp. access specifies the access control for thoseN NTP sites that are not handled by the main 
InterN dtN ews daemon innd(8). Thennrpd(8) server reads it when first spawned by innd. 

Comments begin with a number sign (#) and continue through the end of the line Blank lines and comments are ignored. 
All other lines should consist of five fields separated by colons 


T hefirst field is a wiidmat(3)-style pattern specifying the names or I nternet address of a set of hosts. Before a match is 
checked, the client's hostname (or its Internet address if gethostbyaddr(3) fails) isconverted to lowercase Each line is 
matched in turn, and the last successful match istaken as the correct one 

The second field is a set of letters specifying the permissions granted to the client. The per ms should be chosen from the 
following set: 

r Thedient can retrieve articles 

p Thedient can post articles 

T he third and fourth fields specify the u s e r n a me and p a s s wo r d that the client must use to authenticate themselves before the 
server will accept any articles N otethat no authentication (other than a matching entry in thisfile) is required for 
newsreading. If they are empty, then no password is required. Whitespace in these fields will result in thedient being unable 
to properly authenticate themselves and may be used to disable access. 

Thefifth field isa set of patterns identifying the newsgroups that the client is allowed to access Thepatterns are interpreted 
in thesame manner as the newsfeeds(5) file. The default, however, denies access to all groups 

The access file is normally used to provide host-level access control for reading and posting articles. There are times however, 
when this is not sufficient and user-level accesscontrol is needed. Whenever an N NTP authinfo command is used, thennrpd 
server rereads this file and looks for a matching username and password. If the local newsreaders are modified to send the 
authinfo command, then all host entries can have no access and specific users can be granted the appropriate read and post 
access For example: 

## host:perm:user:pass:groups 
## Default is no access. 


## FOO hosts have no password, can read anything. 
.foo.com:Read Post:::* 

## A related workstation can't access FOO newsgroups, 
lenox. foo.net:RP:martha:hiatt:*,!foo.* 
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If the file contains passwords, it should not be world-readable. 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

innd(8), newsfeeds(5), nnrpd(8), wildmat(3) 


nntpsend.ctl 

nntpsend.ctl— List Of Sites to feed via nntpsend. 

DESCRIPTION 

Thefile /news/iib/nntpsend.cti specifies the default list of sites to befed by nntpsend(8). 

Comments begin with a number sign (#) and continue through the end of the line Blank lines and comments are ignored. 
All other lines should consist of four fields separated byacolon. 

Thefirst field is the name of the site as specified in the newsteeds(5) file 
The second field should be the hostname or IP address of the remote site. 

The third field, if non-empty, specifies the default tail truncation size of site's batchfile This is passed to shrinktiie as the -s 
flag. If thisfield isempty, no truncation is performed. 

Thefourth field specifies some default flags passed to innxmit(8). Theflag -a isalways given to innxmit and need not appear 
here If no -t t i me o u t flag is given in thisfidd and on the nntpsend command line, -t iso will be given to innxmit. 

HISTORY 

Written by Landon Curt Noll (chongo@toad.com) for InterNdtNews. 

SEE ALSO 

innxmit(8), newsfeeds(5), nntpsend(8), trunc(l) 


nologin 

noiogin— Prevent usual users from logging into thesystem. 

DESCRIPTION 

If the file /etc/noiogin exists, login(l) will al I ow access only to root. Other users will be shown thecontents of thisfile and 
their logins refused. 

FILES 


/etc/nologin 


SEE ALSO 

login(l), shutdown(8) 


Linux, 29 December 1992 


overview.fmt 


overview, tmt— Format of news overview database 



passed 


DESCRIPTION 

The file /news/iib/overview.fmt specifies the organization of the news overview database. Blank lines and lines beginning 
with a number sign (#) are ignored. Theorder of lines in thisfile is important; it determines theorder in which the fields will 
appear in the database 

Most lines will consist of an article header name, optionally followed by a colon. A trailing set of lines can have the word full 
appear after the colon; this indicates that the header should appear as well as its value. 

If this file is changed, it is usually necessary to rebuild theexisting overview database using expireover(8) after removing all 
existing overview files 

The default file, show here, is compatible with Geoff Collyer'snov package; 

Subject: 

From: 

Date: 

Message-ID: 

References: 

## Some newsreaders get better performance if Xref is present 
#Xref:full 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for InterN dtN ews. Intended to be compatible with thenov package written by 
Geoff Col Iyer (geoff@world.std.com). 


passwd 

passwd- Password file 


passwd is an ASC11 file that contains a list of the system's users and the passwords they must use for access T he password file 
should have general read permission (many utilities, such asis(l), use it to map user IDsto usernames) but write access only 
for the superuser. 

In the good old days there was no great problem with this general read permission. Everybody could read the encrypted 
passwords, but the hardware was too slow to crack a well-chosen password, and moreover, the basic assumption used to be 
that of a friendly user community. These days, many people run some version of the shadow password suite, where /etc/ 
passwd has *s instead of passwords, and the encrypted passwords are in /etc/shadow, which is readable by root only. 

W hen you create a new login, leave the password field empty and use passwd(l) to fill it. A star (*) in the password field 
means that this user cannot log in via iogin(l). 

There isone entry per line, and each line has the format: 


The field descriptions are 


T he name of the user on the system. 

The encrypted optional user password. 

The numerical user ID. 

The numerical group ID for this user. 

The(optional) comment field (often afull username). 
The user's $home directory. 

The program to run at login (if empty, use /bin/sh). 
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NOTE 

If your root file system ison /dev/ram, you must save a changed password fileto your root filesystem floppy before you shut 
down the system and check the access rights I f you want to create user groups thdr GID s must be equal and there must be 
an entry in /etc/group, or no group will exist. 

FILES 

/etc/passwd 


SEE ALSO 

passwd(l), login(l), group(5), shadow(5) 


Linux, 24July 1993 


passwd.nntp 

passwd.nntp— Passwords for connecting to remoteN NTP servers 

DESCRIPTION 

Thefile /news/iib/passwd.nntp contains host-name-password triplets for use when authenticating client programs to N NTP 
servers. Thisfile is normally interpreted bytheNNTPsend-password routine in iibinn(3). Blank lines and lines beginning with 
anumbersign (#) are ignored. All other lines should consist of three or fields separated by colons: 


Thefirst field is the name of a host and is matched in a case-insensitive manner. The second field is a username, and the 
third isa password. The optional fourth field specifies the type of authentication to use The default is authinfo, which 
means that N NTP authinfo commands are used to authenticate to the remote host. If either the username or password are 
empty, then the related command will not be sent. (The authinfo command isacommon extension to RFC 977.) For 
example: 

## UUNET needs a password, MIT doesn't. 

mit.edu:bbn::authinfo 

uunet.uu.net:bbn:yoyoma:authinfo 

Thisfile should not be world-readable. 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

innd(8), libinn(3) 


pbm 

pbm— Portable bitmap file format. 

DESCRIPTION 

The portable bitmap format isa lowest common denominator monochrome file format. It was originally designed to make it 
reasonable to mail bitmaps between different types of machines using the typical stupid network mailers we have today. Now 
it serves as the common language of a large family of bitmap conversion filters The definition is as follows 
A "magic number" for identifying thefile type. A pbm file's magic number is the two characters pi. 




Whitespace(blanks, Tabs, CRs, LFs). 

A width, formatted as ASC11 characters in decimal. 

Whitespace 

A height, again in ASCII decimal. 

Whitespace 

W idth * height bits, each either i or 0, starting at the top-left corner of the bitmap, proceeding in normal English reading 
order. 

The character 1 means black; 0 means white 
Whitespace in the bits section is ignored. 

C haracters from a # to the next end-of-line are ignored (comments). 

N 0 line should be longer than 70 characters. 

H ere is an example of a small bitmap in this format: 

# feep.pbm 


011110011110011110011110 

010000010000010000010010 



010000011110011110010000 

000000000000000000000000 

Programs that read thisformat should be as lenient as possible, accepting anything that looks remotely like a bitmap. 

There is also a variant on the format, available by setting the rawbits option at compile time T his variant isdifferent in the 
following ways 

The "magic number" isP4 instead of pi. 

T he bits are stored eight per byte, high bit first and low bit last. 

No whitespace isallowed in the bits section, and only a single character of whitespace (typically a newline) is allowed after 
the height. 

The files are eight times smaller and many timesfasterto read and write 

SEE ALSO 

atktopbm(l), brushtopbm(l), cmuwmtopbm(l), g3topbm(l), gemtopbm(l), icontopbm(l), macptopbm(l), mgrtopbm(l), pi3topbm(l), 
xbmtopbm(l), ybmtopbm(l), pbmto10x(l), pnmtoascii(l), pbmtoatk(l), pbmtobbnbg(l), pbmtocmuwm(l), pbmtoepson(l), pbmtog3(l), 
pbnrtogem(l), pbmtogo(l), pbmtoicon(l), pbmtolj(l), pbmtomacp(l), pbmtomgr(l), pbmtopi3(l), pbmtoplot(l), pbmtoptx(l), 
pbmtoxl0bm(l), pbmtoxbm(l), pbmtoybm(l), pbmtozinc(l), pbmlife(l), pbmmake(l), pbmmask(l), pbmreduce(l), pbmtext(l), 
pbmupc(l), pnm(5), pgm(5), ppm(5) 

AUTHOR 

Copyright 1989,1991 byjef Poskanzer. 

27 September 1991 



pgm— Portable graymap file format. 
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DESCRIPTION 

The portable graymap format is a lowest common denominator grayscale file format. The definition isas follows: 

A "magic number" for identifying thefile type. A pgm file's magic number is the two characters P2. 

Whitespace(blanks, Tabs, CRs, LFs). 

A width, formatted as ASC11 characters in decimal. 

Whitespace 

A height, again in ASCII decimal. 

Whitespace 

The maximum gray value, again in ASC 11 decimal. 

Whitespace 

Width * height gray values, each in ASC 11 decimal, between 0 and the specified maximum value, separated by whitespace, 
starting at the top-left corner of the graymap, proceeding in normal English reading order. A value of 0 means black, and the 
maximum value means white 

Charactersfrom a# to the next end-of-lineare ignored (comments). 

N 0 line should be longer than 70 characters. 

Hereisan example of a small graymap in thisformat: 


# feep.pgm 



033330077770011 11 1111 0 0 15 1515 15 0 
030000070000011 00000 15 00 150 



030000077770011 11 1111 0 0 15 0 0 0 0 
000000000000000000000000 


Programs that read thisformat should be as lenient as possible accepting anything that looks remotely like a graymap. 
There is also a variant on the format, available by setting the rawbits option at compile time T his variant isdifferent in the 
following ways 

The"magic number" isps instead of P2. 

The gray values are stored as plain bytes instead of ASCII decimal. 

N 0 whitespace isallowed in the grays section, and only a single character of whitespace (typically a newline) isallowed after 
themaxval. 

Thefiles are smaller and many times faster to read and write 

Note that this raw format can only be used for maxvals less than or equal to 255. If you use the pgm library and try to write a 
file with a larger maxval, it will automatically fall back on the slower but more general plain format. 

SEE ALSO 

fitstopgm(l), fstopgm(l), hipstopgm(l), lispmtopgm(l), psidtopgm(l), rawtopgm(l), pgmbentley(l), pgmcrater(l), pgmedge(l), 
pgmenhance(l), pgmhist(l), pgmnorm(l), pgmoil(l), pgmramp(l), pgmtexture(l), pgmtofits(l), pgmtofs(l), pgmtolispm(l), 
pgmtopbm(l), pnm(5), pbm(5), ppm(5) 

AUTHOR 

Copyright 1989,1991 byjef Poskanzer. 



12 N ovember 1991 
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pnm 

prim— Portable anymap file format. 

DESCRIPTION 

The pnm programs operate on portable bitmaps, graymaps, and pixmaps produced bythepbm, pgm, and ppm segments There is 
no file format associated with pnm itself. 

SEE ALSO 

anytopnm(l), rasttopnm(l), tifftopnm(l), xwdtopnm(l), pnmtops(l), pnmtorast(l), pnmtotiff(1), pnmtoxwd(l), pnmarith(l), 
pnmcat(l), pnmconvol(l), pnmcrop(l), pnmcut(l), pnmdepth(l), pnmenlarge(l), pnmfile(l), pnmflip(l), pnmgamma(l), pnmindex(l), 
pnminvert(l), pnmmargin(l), pnmnoraw(l), pnmpaste(l), pnmrotate(l), pnmscale(l), pnmshear(l), pnmsmooth(l), pnmtile(l), 
ppm(5), pgm(5), pbm(5) 

AUTHOR 

Copyright 1989,1991 byjef Poskanzer. 

27 September 1991 


ppm 

ppm— Portable pixmap file format. 

DESCRIPTION 

The portable pixmap format isa lowest common denominator color image file format. The definition isas follows: 

A "magic number" for identifying thefile type. A ppm file's magic number is the two characters P3. 

Whitespace (blanks, Tabs CRs LFs). 

A width, formatted as ASC11 characters in decimal. 

Whitespace 

A hdght, again in ASCII decimal. 

Whitespace 

The maximum color-component value, again in ASCII decimal. 

Whitespace 

Width * height pixels, each three ASC 11 decimal values between 0 and the specified maximum value, starting at the top-left 
corner of the pixmap, proceeding in normal English reading order. The three values for each pixel represent red, green, and 
blue; a value of 0 meansthat color isoff, and the maximum value means that color is maxed out. 

Charactersfrom a# to the next end-of-lineare ignored (comments). 

N 0 line should be longer than 70 characters. 

H ere isan example of a small pixmap in thisformat: 

P3 

# feep.ppm 


15 

000000000 15 0 15 
0000 15 7000000 
0000000 15 7000 
15 0 150 0 0 00 0 0 0 0 


Programs that read thisformat should be aslenient as possible accepting anything that looks remotely like a pixmap. 
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There isalso a variant on theformat, available by setting the rawbits option at compile time This variant isdifferent in the 
following ways; 

The "magic number" isP6 instead of P3. 

The pixel values are stored as plain bytes, instead of ASCII decimal. 

W hitespace is not allowed in the pixels area, and only a single character of whitespace (typically a newline) is allowed after 
themaxval. 

Thefiles are smaller and many times faster to read and write 

Note that this raw format can only be used for maxvals less than or equal to 255 . If you use the ppm library and try to write a 
file with a larger maxval, it will automatically fall back on theslower but more general plain format. 

SEE ALSO 

giftoppm(l), gouldtoppm(l), ilbmtoppm(l), imgtoppm(l), mtvtoppm(l), pcxtoppm(l), pgmtoppm(l), piltoppm(l), picttoppm(l), 
pitoppm(l), qrttoppm(l), rawtoppm(l), rgb3toppm(l), sldtoppm(l), spctoppm(l), sputoppm(l), tgatoppm(l), ximtoppm(l), 
xpmtoppm(l), yuvtoppm(l), ppmtoacad(l), ppmtogif(l), ppmtoicr(l), ppmtoilbm(l), ppmtopcx(l), ppmtopgm(l), ppmtopil(1), 
ppmtopict(l), ppmtopj(1), ppmtopuzz(l), ppmtorgb3(l), ppmtosixel(l), ppmtotga(l), ppmtouil(l), ppmtoxpm(l), ppmtoyuv(l), 
ppmdither(l), ppmforge(l), ppmhist(l), ppmmake(l), ppmpat(l), ppmquant(l), ppmquantall(l), ppmrelief(l), pnm(5), pgm(5), pbm(5) 

AUTHOR 

Copyright 1989,1991 byjef Poskanzer. 

27 September 1991 


I proc 

/proc- Process information pseudo-filesystem. 

DESCRIPTION 

/proc isa pseudo-filesystem that is used as an interface to kernel data structures rather than reading and interpreting /dev/ 
kmem. M ostof it is read-only, but some files allow kernel variables to be changed. 

Thefollowing outline gives a quick tour through the/proc hierarchy. 

[number ] There is a numerical subdirectory for each running process; the subdirectory is named by the 

process ID. Each containsthefollowing pseudo-files and directories, 
cmdiine Thisholdsthecompletecommand line for the process, unless the whole process has been swapped 

out or unless the process isa zombie In either of these later cases, there is nothing in this file: That 
is, a read on thisfilewill return as having read 0 characters. Thisfile isnull-terminated but not 
newlineterminated. 

cwd T his is a link current working directory of the process. To find out the cwd of process 20, for 

instance, you can do this: cd /proc/ 20 /cwd; /bin/pwd. N ote that the pwd command is often a shell 
built in and might not work properly in thiscontext. 

environ Thisfile contains the environment for the process. The entries are separated by null characters, and 

there may be a null character at the end. Thus, to print out the environment of process 1, you 
would do 

(cat /proc/1/environ; echo) | tr "\000" "\n" 

Fora reason why one should want to do this, see iiio(8). 

exe A pointer to the binary that was executed and appears as a symbolic link. readiink(2) on theexe 

special file returns a string in theformat: 

[devi ce ] :i node 

For example, [03011:1502 is inode 1502 on device major 03 (IDE, M FM, and so on drives), minor 



01 (first partition on the first drive). Also, the symbolic link can be dereferenced normally; 
attempting to open exe will open the executable You can even type/pnoc/[number ]/e«e to run 
another copy of the same process as [number ]. 
find(l) with the -inum option can be used to locate thefile 

Thisisa subdirectory containing oneentry for each file that the process has open, named by its file 
descriptor, and that is a symbolic link to the actual file (asthe exe entry does). Thus, 0 is standard 
input, 1 standard output, 2 standard error, and so on. 

Programs that will take a filename but will not take the standard input and that write to a file but 
will not send their output to standard output can be effectively foiled this way, assuming that -i is 
theflag designating an input file and -o istheflag designating an output file: 
foobar -i /proc/self/fd/0 -o /proc/self/fd/1 ... 

and you have a working filter. Note that this will not work for programs that seek on their files 
because the files in the fd directory are not seekable 

/proc/seif/fd/N ^approximately the same as/dev/fd/N in someUN IX and U N IX-like systems 
M ost Linux makedev scripts symbolically link /dev/fd to /proc/seif/fd, in fact. 

A file containing the currently mapped memory regions and their access permissions 
The format is 


00000000-0002f000 r-x- 00000400 03:03 1401 

0002f000-00032000 rwx-p 0002f400 03:03 1401 

00032000-0005b000 rwx-p 00000000 00:00 0 

60000000-60098000 rwx-p 00000400 03:03 215 

60098000-600c7000 rwx-p 00000000 00:00 0 

bfffa000-c0000000 rwx-p 00000000 00:00 0 


address is the address space in the process that it occupies perms is a set of permissions r =read, w 
=write, x = execute, s = shared, p = private (copy on write). 

offset isthe offset into the fiie/what ever, dev is the device (major: minor), and i node istheinode 
on that device. 0 indicates that no inode isassociated with the memory region, as the case would be 

With bss. 

This is not the same as the mem (1,1) de/ice, despite the fact that it has the same device numbers. 
The/dev/mem device is the physical memory before any address translation is done, butthemem file 
here is the memory of the process that accesses it. This cannot be mmap(2)ed currently, and will not 
be until ageneral mmap(2) isadded to the kernel. (This might have happened by the time you read 
this) 

D i rectory of maps by mmap(2) that are symbolic links such asexe, fd/*, and so on. N otethat maps 
includes a superset of this information, so /proc/*/mmap should be considered obsolete 
0 is usually iibc.so.4. 

/proc/*/mmap was removed in Linux kernel version 1.1.40. (It really was obsolete!) 

U NIX and Linux support the idea of a per-process root of the filesystem, set by thechroot(2) 
system call, root points to the filesystem root and behaves asexe, fd/*, and soon do. 

Status information about the process This is used by ps(l). Thefields in order, with their proper 

scanf(3) format specifiers are 

pid %d TheprocessID. 

comm %s Thefilenameoftheexecutablein parentheses This is visible whether or not 

the executable is swapped out. 
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ppid %d 
pgrp %d 
session %d 
tty %d 
tpgid %d 

flags %u 


minflt %u 

cminflt %u 
majflt %u 

cmajflt %u 


cutime %d 

cstime %d 

counter %d 

timeout %u 
itrealvalue %u 

starttime %d 
vsize %u 


startcode %u 
endcode %u 
startstack %u 
kstkesp %u 


One character from the string rsdzt where r is running, s is sleeping in an 
interruptible wait, Dissleeping in an uninterruptible wait or swapping, z is 
zombie and t is traced or stopped (on a signal). 

ThePID of the parent. 

The process group ID of the process 
The session ID of the process 
The tty the process uses 

T he process group ID of the process that currently owns the tty that the 
process is connected to. 

T he flags of the process C urrently, every flag has the math bit set because 
crte.s checks for math emulation, so this is not included in theoutput. This 
is probably a bug because not every process is a compiled C program. The 
math bit should beadecimal 4, and thetraced bit isdecimal 10. 

T he number of minor faults the process has made, those that have not 
required loading a memory page from disk. 

The number of minor faults that the process and its children have made 
T he number of major faults the process has made those that have requi red 
loading a memory page from disk. 

The number of major faults that the process and its children have made. 

The number of jiffies that this processhas been scheduled in user mode. 

The number of jiffies that this process has been scheduled in kernel mode. 
The number of jiffies that this process and its children have been scheduled 
in user mode 

The number of jiffies that this process and its children have been scheduled 
in kernel mode. 

The current maximum size in jiffies of the process's next timeslice, or what is 
currently left of its current timeslice if it is the currently running process 
Thestandard nice value plus fifteen. The value is never negativein the 
kernel. 

T he time in jiffies of the process's next timeout. 

The time (in jiffies) before the next sigalrm issent to the process due to an 
interval timer. 

Time the process started in jiffies after system boot. 

Virtual memory size 

Resident set size N umber of pages the processhasin real memory, minus3 
for administrative purposes T his isjust the pages that count toward text, 
data, or stack space. This does not include pages that have not been demand- 
loaded in or that are swapped out. 

Current limit in bytes on therss of the process (usually 2,147,483,647). 

The address above which program text can run. 

The address below which program text can run. 

T he address of the start of the stack. 

The current value of esp (32-bit stack pointer), as found in the kernel stack 
page for the process 

The current eip (32-bit instruction pointer). 

The bitmap of pending signals (usually 0). 

The bitmap of blocked signals (usually 0,2 for shells). 



sigignore %d Thebitmap of ignored signals, 

sigcatch %d Thebitmapofcatchedsignals. 

wchan %u This is the "channel" in which the process is waiting. This is the address of a 

system call and can be looked up in a namelist if you need a textual name (If 
you have an up-to-date /etc/psdatabase, then try ps -1 to see the wchan field 
in action.) 

cpuinfo This is a collection ofCPU and system architecture dependent items: for each supported architec¬ 

ture is a different list. The only two common entries are cpu, which istheCPU currently in use 
and BogoMiPs, a system constant that is calculated during kernel initialization, 
devices Text listing of major numbers and device groups This can be used by makedev scriptsfor consis¬ 

tency with the kernel. 

dma This is a list of the registered ISA DMA (direct memory access) channels in use. 

filesystems A text listing of thefi lesystems that were compiled into the kernel. Incidentally, this is used by 

mount(l) to cycle through different filesystems when none isspecified. 
interrupts This is used to record the number of interrupts per each IRQ on (at least) the i386 architecture. 

Very easy to read formatting done in ASCII. 

ioports This is a list of currently registered input-output port regionsthat are in use 

kcore Thisfile representsthephysical memory of the system and isstored in thecorefileformat. With 

thispseudo-fileand an unstripped kernel (/usr/src/iinux/toois/zSystem) binary, gdb can be used 
to examine the current state of any kernel data structures. 

Thetotal length of the file is the size of physical memory (RAM ) plus4KB. 
kmsg Thisfilecan be used instead of thesysiog(2) system call to log kernel messages. A processmust 

have superuser privileges to read thisfile and only one process should read thisfile This file should 
not be read if a sysiog process is running that uses the sysiog(2) system call facility to log kernel 
messages 

Information in thisfile is retrieved with thedmesg(8) program, 
ksyms This holds the kernel exported symbol definitions used by the modules<x> toolsto dynamically link 

and bind loadable modules. 

loadavg The load average numbers give the number of jobs in the run queue averaged over 1,5, and 15 

minutes They are the same as the load average numbers given by uptime(l) and other programs, 
maiioc Thisfile isonly present if configdebugmalloc was defined during compilation, 

meminfo This is used by free(l) to report the amount of free and used memory (both physical and swap) on 

the system as well as the shared memory and buffers used by the kernel. 

It is in the same format as fnee(l) except in bytes rather than KB. 
modules A text list of the modules that have been loaded by the system. 

net Various net pseudo-files all of which give the status of some part of the networking layer. These 

files contain ASC 11 structures and are therefore readable with cat. H owever, the standard 
netstat(8) suite provides much cleaner access to these files 

arp This holds an ASCII readable dump of the kernel ARP table used for address resolutions It will 

show both dynamically learned and pre-programmed ARP entries. Theformat is 

IP address HW type Flags HW address 

10.11.100.129 0x1 0x6 00:20:8A:00:0C:5A 

10.11.100.5 0x1 0x2 00:C0:EA:00:00:4E 

44.131.10.6 0x3 0x2 GW4PTS 


ip address isthe IPv4 address of the machine. The hw type isthehardwaretypeoftheaddressfrom 
RFC 826. The flags are the internal flagsof the ARP structure (as defined in /usr/inciude/iinux/ 
if_arp.h) andtheHW address isthe physical layer mapping for that IP addressif it is known. 
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The dev pseudo-file contains network device status information. This gives the number of received 
and sent packets, the number of errors and collisions, and other basic statistics. These are used by 
the if conf ig(8) program to report de/ice status The format is 

Inter-] Receive i Transmit 

face |packets errs drop fifo frame!packets errs drop fifo colls carrier 
lo: 0 0 0 0 0 2353 0 0 0 0 0 

eth0: 644324 1001 563770 0 0 0 581 0 


No information. 

No information. 

Thisfile uses the same format as the ARP file and contains the current reverse mapping database 
used to provide rarp(8) reverse address lookup services If rarp is not configured into the kernel, 
thisfilewill not be present. 

H olds a dump of the RAW socket table. M uch of the information is not of use apart from 
debugging. The si value is the kernel hash slot for the socket; theiocai_address is the local address 
and protocol number pair, st istheinternal status of the socket. Thetx_queue and rx_queue are the 
outgoing and incoming data queue in terms of kernel memory usage. T he tr, tm->when, and rexmits 
fields are not used by RAW. Theuid field holds the creator euid of the socket. 

N o information but looks similar to route(8). 

Thisfile holds theASC 11 data needed for the IP, ICM P,TCP, and UDP management information 
bases for an snmp agent. As of writing, the TCP mib isincomplete. It should be completed by 1.2.0. 
Holds a dump of the TCP socket table. M uch of the information is not of use apart from 
debugging. The si value is the kernel hash slot for the socket; theiocai_address is the local address 
and port number pair. The remote_address is the remote address and port number pair (if 
connected), st istheinternal status of the socket. Thetx_queue and rx_queue are the outgoing and 
incoming data queue in terms of kernel memory usage. Thetr, tm->when, and rexmits fields hold 
internal information of the kernel socket state and are only useful for debugging. Theuid field 
holds the creator euid of the socket. 

H olds a dump of the U D P socket table. M uch of the information is not of use apart from 
debugging. The si value is the kernel hash slot for the socket; theiocai_address is the local address 
and port number pair. The remote_address is the remote address and port number pair (if 
connected), st istheinternal status of the socket. Thetx_queue and rx_queue are the outgoing and 
incoming data queue in terms of kernel memory usage. Thetr, tm->when, and rexmits fields are not 
used by UDP. Theuid field holds the creator euid of the socket. Theformat is 

si local_address rem_address st tx_queue rx_queue tr rexmits tm->when uid 
1: 01642089:0201 0C642C89:03FF 01 00000000:00000001 01:000071BA 00000000 0 


Lists theUN IX domain sockets present within thesystem and their status Theformat is 

Num RefCount Protocol Flags Type St Path 
0: 00000002 00000000 00000000 0001 03 

1: 00000001 00000000 00010000 0001 01 /dev/printer 

Num isthe kernel table slot number, RefCount isthe number of users of the socket, protocol is 
currently alwayso, and Flags represents the internal kernel flags holding the status of the sockdt. 
Type iscurrently always i (UNIX domain datagram sockets are not yet supported in the kernel), st 
istheinternal state of the socket and Path is the bound path (if any) of the socket. 
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pci This is a listing of all PCI devicesfound during kernel initialization and their configuration, 

scsi A directory with the SCSI mid-level pseudo-file and variousSCSI low-level driver directories, 

which contain a file for each SCSI host in this system, all of which give the status of some part 
of the SC SI 10 subsystem. These filescontain ASCII structuresand are therefore readable with 


driver-name 


self 


u 3357 0 4313 1 


page 5741 1808 
swap 1 0 
intr 1462898 
ctxt 115315 
btime 769041601 
sys 




You can also write to some of the files to reconfigure the subsystem or switch certain features on 
or off. 

T his is a listing of all SC SI devices known to the kernel. T he listing is similar to the one seen 
during bootup, scsi currently supports only the single device command, which allows root to 
add a hot-plugged device to the list of known devices 

An echo 'scsisingledevicel 0 5 0'> /proc/scsi/scsi Will Cause host scsil to Scan On SCSI 
channel 0 fora deviceon ID 5 LUN 0. If there is already a device known on this addressor the 
address is invalid, an error will be returned. 

drivername Can Currently be NCR53c7xx, aha152x, aha1542, aha1740, aic7xxx, buslogic, eata_dma, 
eata_pio, fdomain, in2000, pas16, qlogic, scsi_debug, Seagate, t128, u15-24f, ultrastor, or 

wd7000. These directories show up for all drivers that registered at least one SC SI H BA. Every 
directory contains one file per registered host. Every host-file isnamed after the number the 
host got assigned during initialization. 

Reading these files will usually show driver and host configuration, statistics, and so on. 

Writing to these files allows different things on different hosts. For example, with the latency 
and noiatency commands, root can avitch on and off command latency measurement code in 
the eata_dma driver. W ith the lockup and unlock commands, root can control bus lockups 
simulated by thescsi_debug driver. 

This directory refers to the process accessing the/proc filesystem and isidentical to the/proc 
directory named by the process ID of the same process 
kernel/system Statistics. 

The number of jiffies (l/100ths of a second) that the system spent in user mode, user mode 
with low priority (nice), system mode, and the idle task. The last value should be 100 times the 
second entry in the uptime pseudo-file 

The four disk entries are not implemented at this time I'm not even sure what this should be 
because kernel statistics on other machines usually track both transfer rate and I/O s per second 
and this only allows for one field per drive 

The number of pages the system paged in and the number that were paged out (from disk). 

The number of swap pages that have been brought in and out. 

T he number of interrupts received from the system boot. 

T he number of context switches that the system underwent. 

Boottimein seconds since the epoch (January 1,1970). 

This directory (present since 1.3.57) contains a number of files and subdirectories correspond¬ 
ing to kernel variables These variables can be read and sometimes modified using theproc 
filesystem and using the syscti(2) system call. Presently, there are subdirectories kernel, net, 
and vm that each contain more files and subdirectories. 

This Contains the files domainnarae, file-max, file-nr, hostname, inode-max, inode-nr, osrelease, 
ostype, panic, real-root-dev, securelevel, and version, with function fairly dear from the 
name 

The (read-only) filetiie-nr gives the number of files presently opened. The file me-max gives 
the maximum number of open files the kernel is willing to handle. If 1024 is not enough for 
you, try echo 4096 > /proc/sys/kernel/file-max. 

Similarly, the files inode-nr and inode-max indicate the present and the maximum number of 
inodes. 




T he files ostype, osrelease, and version give substrings of /proc/version. 

The file panic gives r/w access to the kernel variable panic_timeout. If this is zero, the kernel will 
loop on a panic; if nonzero, it indicates that the kernel should autoreboot after this number of 
minutes 

The file secureievei seems rather meaningless at present; root is just too powerful. 

This file contains two numbers the uptime of the system (seconds) and the amount of time 
spent in idle process (seconds). 

This string identifies the kernel version that is currently running. For instance: 

Linux version 1.0.9 (quinlan@phaze) #1 Sat May 14 01:51:54 EDT 1994 

cat(l), find(l), free(l), mount(l), ps(l), tr( 1), uptime(l), readlink(2), mmap(2), chroot(2), syslog(2), hier(7), arp(8), 
dmesg(8), netstat(8), route(8), if config(8), procinfo(8) and much more 

C0NF0RMST0 

This roughly conforms to a Linux 1.3.11 kernel. Please update this as necessary! Last updated for Linux 1.3.11. 

CAVEATS 

Note that many strings (the environment and command line) are in the internal format, with subfields terminated by null 
bytes, so you mightfind thatthingsaremorereadableif you useod -cortr "\ 000 " 11 \n" to read them. 

This manual page is incomplete, possibly inaccurate, and is the kind of thing that needs to be updated very often. 

BUGS 

The /proc filesystem may introduce security holes into processes running with chroot(2). For example, if /proc is mounted in 
thechroot hierarchy, a chdir(2) to /proc/i/root will return to the original root of the filesystem. This may be considered a 
feature instead of a bug because Linux does not yet support the fchroot(2) call. 

22 July 1996 
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protocols—The protocols definition file 

DESCRIPTION 

This file is a plain ASCII file, describing the various DARPA Internet protocols that are available from theTCP/IP 
subsystem. It should be consulted instead of using the numbers in theARPA include files or, even worse, just guessing them. 
These numbers will occur in the protocol field of any IP header. 

Keep thisfile untouched because changes would result in incorrect IP packages Protocol numbers and names are specified by 
the D D N N etwork I nformation Center. 

Each line is of thefollowing format: 


Thefields are delimited by spaces or tabs. Empty lines and lines starting with a hash mark (#) are ignored. Remainder of lines 
are also ignored from the occurrence of a hash mark. 

The field descriptions are 


The native name for the protocol-for example, ip, top, orudp. 

The official number for this protocol as it will appear within the IP header. 
0 ptional aliases for the protocol. 
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Thisfile might be distributed over a network using a network-wide naming service such as Yellow Pages/N IS or BIND/ 
Hesoid. 

FILES 

/etc/protocois The protocols definition file. 

SEE ALSO 

getprotoent(3), GuidetoYdlow Pages Service, GuidetoBIND/Hesiod Service 

Linux, 18 October 1995 
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rcsfile— Format of RCS file 

DESCRIPTION 

An RC S file's contents are described by the grammar below. 

The text is free format: space backspace tab, newline, vertical tab, form feed, and carriage return (collectively, whitespace) 
have no significance except in strings. H owever, whitespace cannot appear within an ID, num, or sym, and an RC S file must 
end with a newline. 

Strings are enclosed by If a string contains a @, it must be doubled; otherwise strings can contain arbitrary binary data. 

T he meta syntax uses the following conventions: | (bar) separates alternatives; { and } enclose optional phrases. { and }* 
enclose phrases that can be repeated zero or more times. { and {+enclose phrases that must appear at least once and can be 
repeated. Terminal symbols are in boldface; non-terminal symbols are in italics 

rcstext ::= admin {del t a }* desc {del t at ext }* 

{ branch {num}; } 

Stress {id}*; 

symbol s {sym : num}*; 

locks {1:4 : num}*; {strict ;} 

{ comment {string}; } 

{ expand {string}; } 

{ newphrase }* 



state {id}; 
branches {num}*; 

{ new-phrase }* 



{newphrase }* 
text string 
num it= {digit j .}+ 

digit ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 

id ::= {num} i d c hf4t®' *|i dchar | num}* 

sym {digit}* idchar {i dchar j digit}* 

idchar ::= any visible graphic character except special 

special ::=$], | . ] : j ; ] @ 

string ::= @{any character, with @doubled}*@ 
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Identifiers are case sensitive Keywords arein lowercase only. The sets of keywords and identifiers can overlap. In most 
environments, RCS uses the I SO 8859/1 encoding: visible graphic characters are codes 041-176 and 240-377, and 
whitespace characters are codes 010-015 and 040. 

Dates, which appear after the date keyword, are of theform Y.mm.dd.hh.mm.ss, where / is the year, mm the month (01-12), 
dd the day (01-31), hh the hour (00-23), mm the minute (00-59), and ssthe second (00-60). Y containsjust thelast two 
digits of the year for years from 1900 through 1999, and all the digits of years thereafter. Dates use the Gregorian calendar; 
times useUTC. 

The newphrase productions in the grammar are reserved for future extensions to the format of RCS files No newphrase will 
begin with any keyword already in use 

The delta nodes form a tree. All nodes whose numbers consist of a single pair (such as 2.3, 2.1,1.3, and so on) are on the 
trunk and are linked through the next field in order of decreasing numbers. The head field in the admin node pointsto the 
head of that sequence (containsthe highest pair). The branch node in the admin node indicates the default branch (or 
revision) for most RCS operations If empty, the default branch is the highest branch on the trunk. 

All delta nodes whose numbers consist of 2 n fields (n2) (such as 3.1.1.1, 2.1.2.2, and so on) are linked as follows All nodes 
whose first 2n-l number fields are identical are linked through the next field in order of increasing numbers. For each such 
sequence, the delta node whose number is identical to the first 2n-2 number fields of the deltas on that sequence is called 
the branchpoint. T he branches field of a node contains a list of the numbers of the first nodes of all sequences for which it is 
a branchpoint. Thislist isordered in increasing numbers. 

Thefollowing diagram shows an example of an RCS file's organization. 
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IDENTIFICATION 

Author: Walter F.Tichy, Purdue University, West Lafayette, IN, 47907. M anual PageRevision: 5.6; ReleaseDate: 1995/ 
06/05. Copyright 1982,1988,1989, Walter F. Tichy. Copyright 1990,1991,1992,1993,1994,1995, Paul Eggert. 

SEE ALSO 

rcsintro(l), ci(l), co(l), ident(l), rcs(l), rcsclean(l), rcsdiff(l), rcsmerge(l), rlog(l), W alter F. Tichy, RCS, "A System 
for Version Control," Software- Practice & Experience, 15, 7 (July 1985), 637-654. 

GNU, 5 Junel995 


resolver 

resolver- Resolver configuration file. 

SYNOPSIS 

/etc/resolv.conf 

DESCRIPTION 

The resolver is a set of routines in theC library (resoiv(3)) that provides access to the Internet Domain N ame System. The 
resolver configuration file contains information that is read by the resolver routines thefirst time they are invoked by a 
process The file is designed to be human readable and contains a list of keywords with values that provide various types of 
resolver information. 

0 n a normally configured system, this file should not be necessary. T he only nameserver to be queried wi II be on the local 
machine, the domain name is determined from the host name and the domain search path is constructed from the domain 
name 

Thedifferent configuration options are 

nameserver Internet address (in dot notation) of a nameserver that the resolver should query. U p to 

maxns (currently 3) nameservers may be listed, one per keyword. If there are multiple servers, 
the resolver library queries them in the order listed. If no nameserver entries are present, the 
default isto use the nameserver on the local machine (The algorithm used is to try a 
nameserver, and if the query times out, try the next until you run out of nameservers, and 
then repeat trying all the nameservers until a maximum number of retries are made) 
domain Local domain name Most queries for nameswithin thisdomain can use short names 

relative to the local domain. If no domain entry is present, the domain is determined from 
the local hostname returned by gethostname(2); the domain part istaken to be everything 
after thefirst.. Finally, if the hostname does not contain a domain part, the root domain is 
assumed. 

search Search list for hostname lookup. The search list is normally determined from thelocal 

domain name; by default, it contains only the local domain name This may be changed by 
listing the desired domain search path following the search keyword with spacesortabs 
separating the names. M ost resolver queries will be attempted using each component of the 
search path in turn until a match isfound. N otethat this process may be slow and will 
generate a lot of network traffic if the servers for the listed domains are not local and that 
queries will timeout if no server is available for one of the domains 
The search list is currently limited to six domains with a total of 256 characters, 
sortiist sortiist allows addresses returned by gethostbyname to be sorted. A sort list is specified by 

IP address ndtmask pairs. Thendtmask isoptional and defaults to the natural netmask of 
the net. The IP address and optional network pairs are separated by slashes. Up to 10 pairs 
may be specified. 

sortiist 130.155.160.0/255.255.240.0 130.155.0.0 
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options options allows certain internal resolver variables to be modified. The syntax is 

options option ... 
where opt ion is one of the following: 
debug sets RESDEBUG in res.options. 

ndots :n sets a threshold for the number of dots that must appear in a name given to 
res_query (see resoiver(3)) before an initial absolute query will be made. The default for n is 
i, meani ng that if there are any dots i n a name, the name will be tried fi rst as an absolute 
name before any search list elements are appended to it. 

The domain and search keywords are mutually exclusive. If more than one instance of these keywords is present, the last 
instance wins 

The search keyword of a system's resoiv.conf file can be overridden on a per-process basis by setting the environment 
variable localdomain to a space-separated list of search domains. 

The options keyword of a system's resoiv.conf file can be amended on a per-process basis by setting the environment 
variable res_options to a space-separated list of resolver options as explained previously. 

The keyword and value must appear on a single line, and the keyword (such asnameserver) must start the line The value 
follows the keyword, separated by whitespace 

FILES 

/etc/resolv.conf 

SEE ALSO 

gethostbyname(3), resoiver(3), hostname(7), named(8),NameServer0perationsGuideforBIND 

11 November 1993 


securetty 

securetty—File that lists ttys from which root can log in. 

DESCRIPTION 

/etc/securetty isused by iogin(l); thefilecontainsthede/icenamesof tty lines (one per line, without leading/dev/) on 
which root isallowed to log in. 


FILES 

/etc/securetty 

SEE ALSO 

login(l) 


Linux, 29 December 1992 
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services— Internet network services list. 

DESCRIPTION 

services is a plain ASCII file providing a mapping between friendly textual names for Internet services and their underlying 
assigned port numbers and protocol types Every networking program should look into this file to get the port number (and 



services 


protocol) for its service. TheC library routines getservent(3), getservbyname(3), getservbyport(3), setservent(3), and 
endservent(3) support querying thisfile from programs. 

Port numbers are assigned bythelANA (Internet Assigned N umbers Authority), and their current policy is to assign both 
TCP and U DP protocols when assigning a port number. Therefore, most entries will have two entries, even for TCP-only 
services 

Port numbers below 1024 (so-called low-numbered ports) can only be bound to by root (see bind(2), tcp(7), and udp(7).) 

T his is so that clients connecting to low-numbered ports can trust that the service running on the port is the standard 
implementation and not a rogue service run by a user of the machine. Well-known port numbers specified bythelANA are 
normally located in this root-only space 

The presence of an entry for a service in the services file does not necessarily mean that the service is currently running on 
the machine. See inetd.conf(5) for the configuration of Internet services offered. Notethatnotall networking services are 
started by inetd(8) and so won't appear in inetd.conf(5). In particular, news(N NTP) and mail (SM TP) servers are often 
initialized from the system boot scripts. 

The location of the services file isdefined by path services in /usr/inciude/netdb.h. This is usually set to /etc/services. 
Each line describes one service and isoftheform: 

service- name Thefriendly name the service is known by and looked up under. It is case sensitive. Often, 

the client program is named after theservi ce-name. 
port Theportnumber (in decimal) to use for this service. 

protocol The type of protocol to be used. This field should match an entry in theprotocois(5) file. 

Typical values include tcp and udp. 

aliases An optional space- or tab-separated list of other names for this service (see the Bugs section 

below). Again, the names are case sensitive. 

Either spaces or tabs may be used to separate the fields 

Comments are started by the hash sign (#) and continue until the end oftheline Blank lines are skipped. 

Theservi ce-name should begin in thefirst column of the file because leading spaces are not stripped, servi ce- names can be 
any printable characters excluding space and tab; however, a conservative choice of characters should be used to minimize 
inter-operability problems. For example a-z, 0-9, and hyphen (-) would seem a sensible choice 
Lines not matching this format should not be present in the file (Currently, they are silently skipped by getservent(3), 
getservbyname(3), and getservbyport(3). H owever, this behavior should not be relied on.) 

Asa backwards compatibility feature, the slash (/) between theportnumber and protocol name can in fact be either a si ash 
oracommaf,). Use of the comma in modern installations is depreciated. 

This file might be distributed over a network using a network-wide naming service such as Yellow Pages/N IS or BIND/ 
Hesiod. 

A sample services file might look like this 
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BUGS 

There is a maximum of 35 aliases, duetothewaythegetservent(3) code is written. 

Lines longer than bufsiz (currently 1024 ) characters will be ignored by getservent(3), getservbyname(3), and 
getservbyport(3). H owever, this will also cause the next line to bemisparsed. 

FILES 

/etc/services The Internet network services list 

/usr/include/netdb.h Definition Of _PATH_SERVICES 

SEE ALSO 

getservent(3), getservbyname(3), getservbyport(3), setservent(3), endservent(3), protocols(5), listen(2), inetd.conf(5), 
inetd(8), Assigned N umbers RFC, most recently RFC 1700 (AKA STD 0002), Guide to Yellow PagesService, Guide to 
BIN D/Hesiod Service. 

Linux, 11 January 1996 


shells 

shells- Pathnames of valid login shells 

DESCRIPTION 

/etc/sheiis isa text filethat contains thefull pathnames of valid login shells This file is consulted by chsh(l) and is available 
to be queried by other programs 

EXAMPLES 

/etc/sheiis may contain the following paths: 

/bin/sh 

/bin/csh 

FILES 

/etc/shells 


SEE ALSO 

chsh(l) 


21 November 1993 


syslog.conf 

sysiog.cont— sysiogd(8) configuration file. 

DESCRIPTION 

The syslog.conf file is the configuration filefor the sysiogd(8) program. It consists of lines with two fields: the selector 
field, which specifies the types of messages and priorities to which theline applies and an action field, which specifies the 
action to betaken if a message sysiogd recdved matches the selection criteria. There cannot beany spaces in the action field. 
The selector field is separated from the action field by one or more tab or space characters (T his i s a departure from the 
standard BSD way of doing things both tabs and spaces can be used to separate the selector from the action.) 

The selector functions are encoded as a facility, a period (.), and a level, with no intervening whitespace. Both the facility 
and the level are case insensitive. 



9/^og.conf 


The facility describes the part of the system generating the message and is one of the following keywords auth, authpriv, 
cron, daemon, kern, lpr, mail, mark, news, syslog, user, uucp, and localO through local7. These keywords (with the exception 
of mark) correspond to the similar dv log_ values specified to the openiog(3) and sysiog(3) library routines 
The level describes the severity of the message and is a keyword, optionally preceded by an equals (=), from the following 
ordered list (higher to lower): emerg, alert, crit, err, warning, notice, info, and debug. These keywords correspond to the 
similar dv log_ values specified to thesysiog library routine. 

See sysiog(3) for further descriptions of both thef acuity and level keywords and their significance 

If a received message matches the specified facility and is of the specified level (or a higher level if level was specified without 

=), theaction specified in the action field will betaken. 

M ultiple selectors may be specified for a single action by separating them with semicolon (;) characters It isimportant to 
note however, that each selector can modify the ones preceding it. 

M ultiple facilities may be specified for a single level by separating them with comma (,) characters. 

An asterisk (*) can be used to specify all facilitiesor all levels 

The special facility "mark" receives a message at priority "info" every 20 minutes (see sysiogd(8)). This is not enabled by a 
facility field containing an asterisk. 

The special level "none" disables a particular facility. 

The action field of each line specifies the action to betaken when the selector field selects a message. There are four forms: 
A pathname (beginning with a leading slash). Selected messages are appended tothefile. 

A hostname (preceded by an at (@) sign). Selected messages are forwarded to the sysiogd program on the named host. 

A comma-separated list of users. Selected messages are written to those users if they are logged in. 

An asterisk. Selected messages are written to all logged-in users. 

Blank lines and lines whose first non-blank character isa hash (#) character are ignored. 

EXAMPLES 

A configuration file might appear as follows 

# Log all kennel messages, authentication messages of 

# level notice or higher and anything of level err or 

# higher to the console. 

# Don't log private authentication messages! 

*.err;kern.*;auth.notice;authpriv.none /dev/console 


# Log all the mail messages in one place. 

# Everybody gets emergency messages, plus log tl 


/var/log/messages 

/var/log/debug 

/var/log/secure 

/var/log/maillog 
n another 


@arpa.berkeley.edu 
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# Root and Eric get alert and higher messages. 

‘.alert root,eric 

# Save mail and news errors of level err and higher in a 

# special file. 

UUCP,news.crit /var/log/spoolerr 

FILES 

/etc/sysiog.conf Thesysiogd(8) configuration file 

BUGS 

Theeffects of multiple selectors are sometimes not intuitive For example mail. crit,*. err will select mail facility messages at 
the level of err or higher, not at the level of crit or higher. 

SEE ALSO 

syslog(3), syslogd(8) 

10 May 1991 


termcap 

termcap- Terminal capability database. 

DESCRIPTION 

The termcap database is an obsolete facility for describing the capabilities of character-cell terminals and printers. It is 
retained only for capability with old programs; new ones should usetheterminfo(5) database and associated libraries, 
/etc/termcap isan ASCII file (the database master) that lists the capabilities of many different types of terminals Programs 
can read termcap to find the particular escape codes needed to control the visual attributes of the terminal actually in use. 
(Other aspects of the terminal are handled by stty.) The termcap database is indexed on the term environment variable, 
termcap entries must be defined on a single logical line with \ used to suppress the newline. Fields are separated by :. The 
first field of each entry starts at the left-hand margin and contains a list of namesfor the terminal, separated by |. 

Thefirst subfield may (in BSD termcap entries from versions4.3 and prior) contain a short name consisting of two 
characters. This short name may consist of capital or small letters In 4.4 BSD termcap entries thisfield isomitted. 

The second subfield (first in the newer 4.4 BSD format) containsthe name used by the environment variable term. It should 
be spelled in lowercase letters Selectable hardware capabilities should be marked by appending a hyphen and a suffix to this 
name Usual suffi xes are w (more than 80 characters wide), am (automatic margins), nam (no automatic margins) and rv 
(reverse video display). The third subfield contains a long and descriptive name for this termcap entry. 

Subsequent fields contain the terminal capabilities; any continued capability lines must be indented onetab from the left 
margin. 

Although there is no defined order, it issuggested to write first Boolean, then numeric, and at last string capabilities, each 
sorted alphabetically without looking at lower or upper spelling. Capabilities of similar functionscan be written in oneline 
Example: 

Head line: vt|vtl01|DEC VT 101 terminal in 80 character mode:\ 

Head line: Vt|vtl01-w|DEC VT 101 terminal in (wide) 132 character mode:\ 

Boolean: :bs:\ 

Numeric: :co#80:\ 

String: :sr=nE[H:\ 
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Boolean Capabilities 


5i 

Printer will not echo on screen 

am 

Automatic margins which means automatic line wrap 

bs 

Ctrl-MH (8 dec.) performs a backspace 

bw 

Backspace on left margin wraps to previous line and right margin 

da 

D isplay retained above screen 

db 

D isplay retained below screen 

eo 

A space erases ail characters at cursor position 

es 

Escape sequences and special characters work in status line 

gn 

Generic device 

he 

T his is a hardcopy terminal 

HC 

The cursor is hard to see when noton bottom line 

hs 

Has a status line 

hz 

H azeltine bug; the terminal cannot print tilde characters 

in 

Terminal inserts nulls, not spaces, to fill whitespace 

km 

Terminal has a mdta key 

mi 

Cursor movement works in insert mode 

ms 

C ursor movement works in standout/underline mode 

NP 

N o pad character 

NR 

ti does not reverse te 

nx 

N o padding; must use XO N /XO FF 

os 

Terminal can overstrike 

ul 

Terminal underlines, although it cannot overstrike 

xb 

Beehive glitch; FI sends Escape and F2 sends "C 

xn 

N ewline/wraparound glitch 

xo 

Terminal usesXON/XOFF protocol 

xs 

Text typed over standout text will be displayed in standout 

xt 

T eleray glitch; destructive tabs and odd standout mode 

Numeric Capabilities 

CO 

Number of columns 

dB 

Delay in millisecondsfor backspace on hardcopy terminals 

dC 

Delay in millisecondsfor carriage return on hardcopy terminals 

dF 

Delay in millisecondsfor form feed on hardcopy terminals 

dN 

Delay in millisecondsfor newlineon hardcopy terminals 

dT 

Delay in millisecondsfor tabulator stop on hardcopy terminals 

dV 

Delay in millisecondsfor vertical tabulator stop on hardcopy terminals 

it 

D ifference between tab positions 

lh 

H eight of soft labels 

lm 

Lines of memory 

lw 

Width of soft labels 


continues 
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Numeric Capabilities 


li 

Number of lines 

N1 

Number of soft labels 

pb 

Lowest baud rate that needs padding 

sg 

Standout glitch 

ug 

Underline glitch 

vt 

Virtual terminal number 

ws 

W idth of status line if different from screen width 

StringCapabilities 

ii 

Shifted save key 

!2 

Shifted suspend key 

!3 

Shifted undo key 

#1 

Shifted help key 

#2 

Shifted home key 

#3 

Shifted input key 

#4 

Shifted cursor left key 

%0 

Redo key 

%1 

Help key 

%2 

M ark key 

%3 

M essagekey 

%4 

M ove key 

%5 

N ext-object key 

%6 

Open key 

%7 

Options key 

%8 

Previous-object key 

%9 

Print key 

%a 

Shifted message key 

%b 

Shifted move key 

%c 

Shifted next key 

%d 

Shifted options key 

%e 

Shifted previous key 

%f 

Shifted print key 

*g 

Shifted redo key 

%h 

Shifted replace key 

%1 

Shifted cursor right key 

%i 

Shifted resume key 

&0 

Shifted cancel key 

8.1 

Reference key 

8.2 

Refresh key 

&3 

Replace key 

&4 

Restart key 
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String Capabilities 

65 

66 
& 7 


@3 

@5 

@6 

@7 


al 


bl 

cb 


cd 


Resume key 
Save key 
Suspend key 
U ndo key 
Shifted begin key 
Shifted find key 
Shifted command key 
Shifted copy key 
Shifted create key 
Shifted delete character 
Shifted delete line 
Select key 
Shifted end key 
Shifted clear line key 
Shifted exit key 
Find key 
Begin key 
C ancel key 
Close key 
Command key 
Copy key 
C reate key 
End key 
Enter/send key 
Exit key 
Insert one line 
Insert%i lines 

Pairs of block graphic characters to map alternate character set 
End alternative character set 

Start alternative character set for block graphic characters 
Backspace if not "FI 
Audio bell 

M oveto previous tab stop 
Clear from beginning of lineto cursor 
D ummy command character 
C lear to end of screen 
Clear to end of line 

M ove cursor horizontally only to column %i 

C lear screen and cursor home 

Cursor move to row %i and column %2 (on screen) 

M ove cursor to row %i and column %2 (in memory) 


continues 
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DC 

dl 

DL 


DO 


ed 

ff 


F2 

F3 


Carriage return 

Scroll region from line%i to %2 
Clear tabs 

M ove cursor vertically only to line %i 

D elete one character 

Delete%i characters 

Delete one line 

D elete%i lines 

Begin delete mode 

Cursor down one line 

Cursor down #1 lines 

Disable status line 

E nable alternate character set 

E rase %i characters starting at cursor 

End delete mode 

End insert mode 

Formfeed character on hardcopy terminals 

Return character to its position before going to status line 

The string sent by function key fll 

The string sent by function key fl2 

The string sent by function key f!3 


F9 Thestringsent by function key fl9 

fa Thestringsent by function key f20 

fb Thestringsent by function key f21 


fz Thestringsent by function key f45 

Fa Thestringsent by function key f46 

Fb Thestringsent by function key f47 


Thestringsent by function key f63 
M ove cursor a half line down 
Cursor home 
Move cursor a half lineup 
Initialization string 1 at login 
Initialization string 3 at login 
Initialization string 2 at login 
Insert one character 
Insert%i characters 
Initialization file 
Begin insert mode 
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K2 

K3 


K5 

k0 


k2 

k3 


k5 

k6 


k8 


kb 

kB 

kC 

kd 

kD 

kE 

kF 


kl 

kl 

kL 


Insert pad time and needed special characters after insert 

Initialization program 

U pper-left key on keypad 

Center key on keypad 

U pper-right key on keypad 

Bottom-left key on keypad 

Bottom-right key on keypad 

Function key 0 

Function key 1 

Function key 2 

Function key 3 

Function key 4 

Function key 5 

Function key 6 

Function key 7 

Function key 8 

Function key 9 

Function key 10 

C lear all tabs key 

Insert line key 

Backspace key 

Back tab stop 

Clear screen key 

C ursor down key 

Key for delete character under cursor 

T urn keypad off 

Key for clear to end of line 

Key for scrolling forward/down 

C ursor home key 

Cursor down key 

I nsert character/insert mode key 

C ursor left key 

Key for delete line 

Key for exit insert mode 

Key for next page 

Key for previous page 

Cursor right key 

Key for scrolling backward/up 

T urn keypad on 

C lear to end of screen key 

Clear this tab key 
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10 

11 

12 


Sdt tab here key 
C ursor up key 

Label of zeroth function key, if not fO 
Label of first function key, if notfl 
Label of first function key, if notf 2 


la 

le 

11 

LE 

LF 

LO 

mb 

MC 

rad 


rap 


nd 

pc 

Pf 

pk 

pl 

po 

pO 


Label of tenth function key, if notflO 
Cursor left one character 
M ove cursor to lower-left corner 
C ursor left %i characters 
T urn soft labels off 
T urn soft labels on 
Start blinking 
Clear soft margins 
Start bold mode 

End all modes such as so, us, mb, md, and mr 

Start half bright mode 

Dark mode(Charactersinvisible) 

Set left soft margin 
Put terminal in meta mode 
Put terminal out of meta mode 
Turn on protected attribute 
Start reverse mode 
Set right soft margin 
C ursor right one character 
Carriage return command 
Padding character 
Turn printer off 

Program key %i to send string %2 as if typed by user 
Program key %i to execute string %2 in local mode 
Program soft label %i to show string %2 
Turn the printer on 

T urn the printer on for %i (< 256 ) bytes 
Print screen contents on printer 
Program key %i to send string %2 to computer 
Reset string 1 to set terminal to sane modes 
Reset string 2 to set terminal to sane modes 
Reset string 3 to set terminal to sane modes 
Disable automatic margins 
Restore saved cursor position 
Reset string file name 
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StringCapabilities 


RF 

Request for input from terminal 

RI 

C ursor right %i characters 

rp 

Repeat character %i for %2 times 

rP 

Padding after character sent in replace mode 

rs 

Reset string 

RX 

Turn off XON/XOFF flow control 

sa 

Set %i %2 %3 %4 %5 %6%7 %8 %9 attributes 

SA 

Enable automatic margins 

sc 

Save cursor position 

se 

End standout mode 

sf 

Normal scroll oneline 

SF 

N ormal scroll %i lines 

so 

Start standout mode 

sr 

Reverse scroll 

SR 

Scroll back %i lines 

St 

Set tabulator stop in all rows at current column 

SX 

T urn on XON/XOFF flow control 

ta 

M ove to next hardware tab 

tc 

Read in terminal description from another entry 

te 

End program that uses cursor motion 

ti 

Begin program that uses cursor motion 

ts 

M ove cursor to column %i of status line 

uc 

U nderline character under cursor and move cursor right 


End underlining 

up 

Cursor up oneline 

UP 

Cursor up %i lines 

US 

Start underlining 

vb 

Visible bell 

ve 

N ormal cursor visible 

Vi 

Cursor invisible 

VS 

Standout cursor 

wi 

Set window from line %i to %2 and column %3 to %4 

XF 

XOFF character if not A S 

There are several ways of defining the control codes for string capabilities: 

N ormal characters except", 

\, and % represent themselves. 

A “x meansCtrl+x. CtrHA equals 1 decimal. \* meansaspecial code, x can beoneof thefollowingcharacters 

E 

Escape (27). 

n 

Linefeed (10). 

r 

Carriage return (13). 

t 

Tabulation (9). 
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b Backspace (8). 

f Form feed (12). 

0 N ull character. A \*x* specifies the octal characterxxx. 

1 Increments parameters by one. 

r Single parameter capability. 

+ Add value of next character to this parameter and do binary output. 

2 D o ASC11 output of this parameter with a field width of 2. 

d D o ASC 11 output of this parameter with a field width of 3. 

% Print a % 

If you use binary output, then you should avoid the null character because it terminates the string. You should reset tabulator 
expansion if a tabulator can be the binary output of a parameter. 

W arning: The preceding metacharacters for parameters may bewrong; they document M inix termcap, which may not be 
compatible with Linux termcap. 

The block graphic characters can be specified by three string capabilities: 
as Start the alternative charset, 

ae End it. 

ac Pai rs of characters T he first character is the name of the block graphic symbol and 

thesecond character is its definition. 


T hefollowing name are available: 


Right arrow (>) 

Left arrow (<) 

Down arrow (v) 

Full square (#) 

Latern (#) 

Upper arrow (") 

Rhombus (+) 

Chessboard (:) 

Degree(') 

Plus-minus (#) 

Square (#) 

Right bottom corner (+) 
Right upper corner (+) 
Left upper corner (+) 

Left bottom corner (+) 
Cross(+) 

Upper horizontal line{-) 
M iddle horizontal line(-) 
Bottom horizontal line(_) 
Left tee (+) 

Right tee(+) 

Bottom tee (+) 

N ormal tee (+) 

Vertical line(_) 

Paragraph (???) 
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The value in parenthese are suggested defaults that are used by curses if thecapabilitieare missing. 

SEE ALSO 

termcap(3), curses(3), terminfo(5) 

L inux 


ttytype 

ttytype— Terminal name and device list. 

DESCRIPTION 

The/etc/ttytype file associates termcap/terminfo terminal type names with tty line Each line consists of a terminal type, 
followed by whitespace, followed by a tty name (a device name without the /dev/ prefix). 

This association is used by the program tset(l) to set the environment variable term to the default terminal name for the 
user's current tty. 

Thisfacility was designed for a traditional time-sharing environment featuring character-cell terminals hardwired to aUN IX 
minicomputer. It is little used on modern workstation and personal U N IXes. 

EXAMPLE 

A typical /etc/ttytype is 

con80x25 ttyl 
vt320 ttys0 

FILES 

/etc/ttytype Thetty definitions file 

SEE ALSO 

getty(l), terminfo(5), termcap(5) 

Linux, 24 July 1993 


tzfile 

tzfile- T ime zone i nformation. 

SYNOPSIS 

//include <tzfile.h> 


DESCRIPTION 


The time zone information files used by tzset(3) begin with bytes reserved for future use, followed by six four-byte values of 
type long, written in a "standard" byte order (the high-order byte of the value is written first). These values are, in order 


tzh_ttisgmtcnt 

tzh_ttisstdcnt 

tzh_leapcnt 

tzh_timecnt 

tzh_typecnt 

tzh_charcnt 


The number of GMT/local indicators stored in thefile. 

T he number of standard/wall indicators stored in thefile. 

The number of leap secondsfor which data isstored in thefile. 

The number of "transition times" for which data isstored in thefile. 

The number of "local time types" for which data isstored in thefile (must not be zero). 
T he number of characters of "ti me zone abbreviation stri ngs" stored in the fi le 
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The preceding header isfollowed by tzh_timecnt four-byte values of type long, sorted in ascending order. These values are 
written in "standard" byte order. Each is used as a transition time (as returned by time(2)) at which the rules for computing 
local time change. N ext come tzh_timecnt one-byte values of type unsigned char; each one tells which of the different types 
of "local time" types described in the file is associated with the same-indexed transition time These values serve as indices 
into an array of ttinto structures that appears next in thefile; these structures are defined as follows 


struct ttinto { 
long tt_gmtoff; 



E ach structure is written asa four-byte value for tt_gmtott of type long, in a standard byte order, followed by a one-byte 
value for tt_isdst and a one-byte value for tt_abbrind. In each structure, tt_gmtott gives the number of seconds to be added 
to GMT, tt_isdst tells whether tm_isdst should be set by iocaitime(3) and tt_abbrind serves as an index into the array of 
ti me zone abbreviation characters that follow the ttinto structures in the file. 

Then there are tzh_ieapcnt pairs of four-byte values written in standard byte order; thefirst valueof each pair gives thetime 
(as returned by time{2)) at which a leap second occurs; the second gives the total number of leap seconds to be applied after 
the given time. The pairs of values are sorted in ascending order by time 

Then there are tzh_ttisstdcnt standard/wall indicators each stored as a one-byte value; they tell whether thetransition times 
associated with local timetypes were specified as standard timeorwall clock time and are used when atimezonefile is used 
in handling PO SIX-style time zone environment variables 

Finally, there are tzh_ttisgmtcnt G M T/local indicators each stored as a one-byte value; they tel I whether thetransition times 
associated with local time types were specified asGM T or local timeand are used when atimezonefile is used in handling 
PO SIX-style time zone environment variables. 

Locaitime uses the first standard-time ttinto structure in the file (or simply thefirst ttinto structure in the absence of a 
standard-time structure) if either tzh_timecnt is zero or thetime argument is less than thefirst transition time recorded in the 
file. 

SEE ALSO 

newctime(3) 

utmp, wtmp 

utmp, wtmp- Login records. 

SYNOPSIS 

#include <utmp.h> 

DESCRIPTION 

T he utmp file allows you to discover information about who iscurrently using the system. T here may be more users currently 
using the system because not all programs use utmp logging. 

W arning: utmp must not be writable because many system programs depend on its integrity. You risk faked system log files 
and modifications of system files if you leave utmp writable to any user. 

The file is a sequence of entries with the following structure declared in the include file: 

#define UTJJNKNOWN 0 
#define RUN_LVL 1 
#define B00T_TIME 2 
#define NEW_TIME 3 
#define 0LD_TIME 4 



utmp, wtmp 


#define INIT_PROCESS 5 
#define LOGIN_PROCESS 6 
#define USER_PROCESS 7 
#define DEAD_PROCESS 8 

#define UT_LINESIZE 12 
#define UT_NAMESIZE 8 
#define UT_HOSTSIZE 16 

struct utmp { 

short ut_type; 
pid_t ut_pid; 

char ut_line[UT_LINESIZE]; 
char ut_id[2]; 
time_t ut_time; 
char ut_user[UT_NAMESIZE]; 
char ut_host[UT_HOSTSIZE]; 
long ut_addr; 


/* type of login */ 

/* pid of process */ 

/* device name of tty - "/dev/" */ 
/* Init id or abbrev, ttyname */ 

/* host name for remote login */ 

/* IP addr of remote host */ 


This structure gives the name of the special file associated with the user's terminal, the user's login name and the time of 
login in theform of time(2). String fields are terminated by \o if they are shorter than the size of the field. 

Thefirst entries ever created result from init(8) processing inittab(5). Before an entry is processed, though, init(8) cleans 
up utmp by setting ut_type to dead_process, clearing ut_user, ut_host and ut_time with null bytesfor each record that ut_type 
is not dead_process or run_lvl and where no process with PID ut_pid exists If no empty record with the needed ut_id can be 
found, init creates a new one It sets ut_id from the tntttab, ut_ptd and ut_time to the current values, and ut_type to 

INIT_PROCESS. 

getty(8) locates the entry by the PI D, changes ut_type to login_process, changes ut_time, sets ut_itne and waits for 
connection to be established. iogtn(8), after a user has been authenticated, changes ut_type to user_process, changes ut_time, 
and sets utjost and ut_addr. D epending on getty(8) and iogin(8), records may be located by ut_iine instead of the 
preferable ut_pid. 

W hen init(8) finds that a process has exited, it locatesits utmp entry by ut_pid, sets ut_type to dead_process, and clears 
ut_user, ut_host, and ut_time with null bytes. 

xterm(l) and other terminal emulators directly create a user_process record and generate the ut_id by using the last two 
letters of /dev/ttyp%c or by using p%d for /dev/pts/%d. 

If they find a dead_process for this ID, they recycle it; otherwise they create a new entry. If they can, they will mark it as 

dead_process on exiting and it is advised that they null ut_iine, ut_time, ut_user, and ut_host as well. 

xdm(8) should not create an utmp record because there is no assigned terminal. Letting it create one will result in trouble such 

aSfinger: cannot stat /dev/machine.dom. It Should Create wtmp entries, though, just like ftpd(8) does 

teinetd(8) setsup a login_process entry and leaves the rest to iogin(8) as usual. After theT elnet session ends, teinetd(8) 

cleans up utmp in the described way. 

The wtmp file records all logins and logouts. Its format is exactly like utmp except that a null username indicates a logout on 
theassociated terminal. Furthermore, the terminal name- with username shutdown or reboot indicates a system shutdown or 
reboot and the pair of terminal names ■ ]"/"}" logs the old/new system time when date(l) changes it. wtmp is maintained by 
iogin(l) and init(l) and some variation of getty(l). Neither of these programs creates the file, so if it is removed, record¬ 
keeping is turned off. 

FILES 

/var/run/utmp 

/var/log/wtmp 
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CONFORMING TO 

Linux utmp entries conform neither to v7/BSD nor to SYSV: They are a mix of the two. v7/BSD has fewer fields; most 
importantly, it lacks ut_type, which causes native v7/BSD-like programs to display (for example) dead or login entries 
Further there is no configuration file that allocatesslots to sessions BSD does so because it lacks ut_id fields In Linux (as in 
SYSV), the ut_id field of a record will never change once it is set, which reserves that slot without needing a configuration 
file. Clearing ut_id may result in race conditions leading to corrupted utmp entries and potential security holes Clearing the 
previously mentioned fields by filling them with null bytes is not required by SYSV semantics but it allows you to run many 
programs that assume BSD semantics and that do not modify utmp. Linux uses the BSD conventions for line contents. SYSV 
only uses the type field to mark them and logs informative messages such as new time in the linefield. SYSV has one more 
field to log the exit status of dead processes, utjjnknown seems to be a Linux invention. There is no type accounting in Linux. 
SYSV has no utjiost or ut_addr fields. Unlike various other systems, where utmp logging can be disabled by removing the 
file, utmp must always exist on Linux. If you want to disable who(l), then do not make utmp world readable. 

RESTRICTIONS 

The file format is machine dependent, so it is recommended that it be processed only on the machine architecture where it 
got created. 


SEE ALSO 

ac(1), date(l), last(l), login(l), who(l), getutent(3), init(8) 
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uuencode 

uuencode— Format of an encoded uuencodefile. 

DESCRIPTION 

Files output by uuencode(l) consist of a header line, followed by a number of body lines, and a trailer line Theuudecode(l) 
command will ignore any lines preceding the header or following the trailer. Linespreceding a header must not, of course, 
look like a header. 

The header line ^distinguished by having the first six characters begin. The word begin isfollowed by a mode (in octal) and 
a string that names the remote file A space separates the three items in the header line 

The body consists of a number of lines, each at most 62 characters long (including thetrailing newline). These consist of a 
character count, followed by encoded characters, followed by a newline The character count isa single printing character 
and represents an integer, the number of bytes the rest of the line represents Such integers are always in the range from 0 to 
63 and can be determined by subtracting the character space (octal 40) from the character. 

Groups of three bytes are stored in four characters, six bits per character. All are offset by a space to make the characters 
print. T he last line may be shorter than the normal 45 bytes If the size is not a multiple of three, this fact can be determined 
by the value of the count on the last line. Extra garbage will be included to make the character count a multiple of four. The 
body is terminated by a line with a count of zero. This line consists of one ASCI I space 
Thetrailer lineconsistsof end on a line by itself. 

SEE ALSO 

uuencode(l), uudecode(l), uusend(l), uucp(l), mail(l) 

HISTORY 

The uuencodefile format appeared in BSD 4.0. 
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XF86Config 

xF86Config— C onfigurati on file for X Free86. 


DESCRIPTION 

XFree86 uses a configuration file called xF86Config for its initial sdtup. This configuration file is searched for in thefollowing 
places: 

/etc/XF86Config 

<XRoot>/lib/X11/XF86Config.host name 
<X R o o t>/lib/X11/XF86Config 

<xRoot > refers to theroot of theXll install tree 

This file is composed of a number of sections Each section hastheform: 

Section "SectionName" 

EndSection 

The section names are 

ServerFlags 
Keyboard 

Monitor 
Device 
Screen 


Filepathnames 
Server flags 

Keyboard configuration 
Pointer configuration 
Monitor description 
G raph i cs devi ce descri ption 
Screen configuration 


The Files section isused to specify the default font path and the path to the RGB database. These paths can also be set from 
thecommand line (see xserver(l)). T heentries availablefor thissection are 

FontPath "path" Sets the search path for fonts. This path is a comma-separated list of directories that the X 

server searches for font databases M ultiple FontPath entries may be specified, and they will 
be concatenated to build up thefontpath used by the server. 

X11R6 allows theX server to request fonts from a font server. A font server isspecified by 
placi ng a ■ <t r a n s > / <h o s t n a me >: <p o r t. n u mb e r > ■ entry i nto the fontpath .For exam pie the 
fontpath 

"/usr/X11R6/lib/X11/fonts/misc/,tcp/zok:7100“ 

tellstheX server to first try to locatethefont in the local directory /usr/xi iR6/iib/xi i / 
fonts/misc. If that fails, then request the font from the font server running on machine zok 
listening for connections on TC P port number 7100. 

RGBPath "path" Sets the path name for the RG B color database 


The ServerFlags section is used to specify some miscellaneous X server options.The entries available for thissection are 
NoTrapSignais This prevents the X server from trapping a range of unexpected fatal signals and exiting 

cleanly. Instead, theX server will dieand drop core where thefault occurred. Thedefault 
behavior isfortheX server exit cleanly but still drop a core file. In general, you never want 
to usethisoption unless you are debugging an X server problem. 

Dontzap This disallows the use of theCtrlfAlt-fBackspacesequence Thissequenceallowsyou to 

terminate theX server, setting Dontzap allows thiskey sequence to be passed to clients 
Dontzoom This disallows the use of theCtrl-tAlt+Keypad-Plusand Ctrl4Alt+K eypad-M in us sequences. 

These sequences allow you to switch between video modes. Setting Dontzoom allows these 
key sequences to be passed to clients 
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The Keyboard section is used to specify the keyboard input device, parameters, and some default keyboard mapping options 
Theentriesavailablefor thissection are 

protocol "kbd-protocoi " kbd- pr ot ocoi may be either standard or xqueue. xqueue isspecified when using theevent 

queue driver on SVR3 orSVR4. 

AutoRepeat delay rate C hanges the behavior of the autorepeat of the keyboard. This does not work on all 

platforms 

serverNumLock Forces the X server to handle the numlock key internally. The X server sends a different sdt 

of keycodesforthenumpad when thenumlock key is active T his enables applicationsto 
make use of the numpad. 

LeftAlt mapping RightAlt mapping AltGr mapping 
ScrollLock mapping RightCtl mapping 

Allows a default mapping to be set for the preceding keys (note that AitGr is a synonym for RightAlt). T he values that may be 

specified for mappi ng are 

Meta 

Compose 

ModeShift 

ModeLock 

ScrollLock 

Control 


The default mapping when none of these options are specified is 
LeftAlt M eta 


RightAlt M eta 
ScrollLock Compose 
RightCtl Control 

XLeds led ... 
VTSysReq 


VTInit "command" 


M akesi ed available for clients instead of using the traditional function (Scroll Lock, Caps 
Lock, and N urn Lock), led isa list of numbers in the range 1 to 3. 
EnablestheSYSV-styleVT a/vitch sequence for non-SYSV systems that support VT 
switching. This sequence is Alt- SysRq followed by a function key (Fn). This prevents theX 
server trapping the keys used for thedefault VT switch sequence. 

Runscommand after theVT used by the server has been opened. Thecommand string is 
passed to /bin/sh -c and is run with the real user's ID with stdin and stdout sdtto thevT. 
The purpose of thisoption isto allow system-dependent VT initialization commands to be 
run. One example is a command to disable the two-key VT switching sequence that is the 
default on some systems 


The Pointer section is used to specify the pointer device and parameters. The entries available for this section are 
protocol "protocol -type" Specifies the pointer device protocol type. T he protocol types avai lable are 


BusMouse 

Logitech 

Microsoft 

MMSeries 

Mouseman 


MouseSystems 

PS/2 
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MMHitTab 

Xqueue 

OSMouse 

One should specify BusMouse for the Logitech bus mouse. Also, many newer Logitech serial mice use either the Microsoft or 
MouseMan protocol, xqueue should be specified here if it was used in the Keyboard section. OSMouse refers to the event-driver 
mouse interface available on SCO's SV R3. This may optionally be followed by a number specifying the number of buttons 
the mouse has. 


BaudRate rate 

Emulate3Buttons 

Emulate3Timeout timeout 

ChordMiddle 
SampleRate rate 
ClearDTR 


ClearRTS 


Specifies the device the server should open for pointer input (such as/dev/ttyoo 
or /dev/mouse). A device should not be specified when using the Xqueue or 
0 SM ouse protocols 

Sdts the baud rate of the seri al mouse to r a t e . F or mice that allow dynamic speed 
adjustments (such as Logitech), the baud rate is changed in the mouse. 

Otherwise, the rate is simply set on the computer's side to allow mice with non¬ 
standard rates (the standard rate is 1200). 

Enables the emulation of the third mouse button for mice that only have two 
physical buttons The third button is emulated by pressing both buttons 
simultaneously. 

Sdts the time (in milliseconds) that the server waits before deciding if two 
buttons were pressed "simultaneously" when three-button emulation is enabled. 
The default time-out is 50ms 

Handles mice that send left-wight events when the middle button is used (such as 
some Logitech M ouseman mice). 

Sdts the number of motion/button-events the mouse sends per second. T his is 
currently only supported for some Logitech mice 
This option clearstheDTR line on the serial port used by the mouse This 
option is only valid for a mouse using theMouseSystems protocol. Some dual¬ 
protocol mice require DTR to be cleared to operate in MouseSystems mode. Note 
in versions of XFree86 prior to 2.1, thisoption also cleared the RT S line A 
separate ciearRTS option has since been added for mice that require this. 
Thisoption clears the RTS line on the serial port used by the mouse Thisoption 
isonly valid for a mouse using the MouseSystems protocol. Some dual-protocol 
mice require both D T R and RT S to be cleared to operate in MouseSystems mode. 
Both the ciearDTR and ciearRTS options should be used for such mice 


The Monitor sections are used to define the specifications of a monitor and a I ist of video modes suitable for use with a 
monitor. M ore than one Monitor section may be present in an xF86Config file. The entriesavailablefor this section are 


Identifier "ID string" 

VendorName "vendor" 
ModelName model " 
HorizSync horizsync-range 


This specifies a string by which the monitor can be referred to in a later screen 
section. Each Monitor section should havea unique ID string. 

This optional entry specifies the monitor's manufacturer. 

This optional entry specifies the monitor's model. 

G i ves the ranges of horizontal sync frequencies supported by the monitor, 
hori zsync-range may be a comma-separated list of either discrete values or ranges 
of values. A range of values istwo values separated by a dash. By default, the 
values are in units of kH z. T hey may be specified in M H zor Hz if M H zor H zis 
added to the end of the line The data given here is used by theX server to 
determine if video modes are within the specifications of the monitor. This 
information should be available in the monitor's handbook. 
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vertRefresh vertrefresh- range G ives the ranges of vertical refresh frequencies supported bythemonitor. 

vertrefresh-range may be a comma-separated list of either discrete values 
or ranges of values A range of values is two values separated by a dash. By 
default, the values are in units of Hz. They may be specified in M Hz or 
kHz if M Hz or kHz is added to the end of the line The data given here is 
used by the X server to determine if video modes are within the 
specifications of the monitor. Thisinformation should be available in the 
monitor's handbook. 

Gamma gamma-values This is an optional entry that can be used to specify the gamma 

correction for the monitor. It may be specified as either a single value or 
as three separate RG B values N ot all X servers are capable of using this 
information. 

Mode "name " Indicates the start of a multi-line video mode description. The mode 

description isterminated with an End-M odeline The mode description 
consists of the following entries 

Dotciock clock The dot clock rate to be used for the mode. 

HTimings hdisp hsyncst art hsyncend htotai Specifiesthe horizontal timingsfor the mode. 

vTimings vdi sp vsyncstart vsyncend vtotai Specifiesthe vertical timingsfor the mode 

Flags "flag" ... Specifies an optional set of modeflags interlace indicatesthat the mode 

is interlaced. DoubieScan indicates a mode where each scanline is doubled, 
■msync and -HSync can be used to select the polarity of the H Sync signal. 
+vsync and -vsync can be used to select the polarity of the V Sync signal. 
composite can beused to specify composite sync on hardware where this is 
supported. Additionally, on some hardware, +csync and -csync may be 
used to select the composite sync polarity. 

Modeline "name" mode-descr i pt i on A single line format for specifying video modes Themode-description is 

in four sections, the first three of which are mandatory. Thefirst isthe 
pixel clock. Thisis a single number specifying the pixel clock rate for the 
mode T he second section is a list of four numbers specifying the 
horizontal timings These numbers are the hdisp, hsyncstart, hsyncend, 
htotai. T he third section isa list of four numbers specifying the vertical 
timings These numbers are vdisp, vsyncstart, vsyncend, vtotai. The final 
section is a list of flags specifying other characteristics of the mode, 
interlace indicates that the mode is interlaced. DoubieScan indicates a 
mode where each scanline is doubled. +HSync and -HSync can beused to 
select the polarity of the HSync signal. +vsync and -vsync can beused to 
select the polarity of the vsync signal, composite can beused to specify 
composite sync on hardware where this issupported. Additionally, on 
some hardware +csync and -csync may be used to select the composite 
sync polarity. 


The Device sections are used to define a graphics device (video board). M ore than one Device section may be present in an 
xF86Config file. The entriesavailablefor this section are 


Identifier "I D str i ng" 

VendorName "vendor" 
BoardName "model " 
Chipset "chipset-type" 


Thisspecifies a string by which the graphics device can be referred to in a 
later screen section. Each Device section should have a unique ID string. 
This optional entry specifies the graphics device's manufacturer. 

T his optional entry specifies the name of the graphics de/ice 
T his optional entry specifies the chipset used on the graphics board. I n 
most cases, this entry is not required because theX servers will probe the 
hardware to determine the chipset type. 
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Ramdac "ramdac-type" 


DacSpeed speed 


Clocks clock ... 


ClockChip "clockchip-type" 

ClockProg command [text clock] 


Option opti onstring 


VideoRam me m 


BIOSBase baseaddress 


This optional entry specifies the type of RAM D AC used on the graphics board. 
This is only used by a few of the X servers and in most cases, it is not required 
because theX servers will probe the hardware to determine the RAM DAC type 
where possible. 

Thisoptional entry specifies the RAM DAC speed rating (which is usually 
printed on the RAM DAC chip). The speed is in MHz. This is only used by a 
few of the X servers and only needs to be specified when the speed rating of the 
RAM DAC is different from thedefault built in to theX server. 
Specifiesthedotdocksthatareon your graphics board. The clocks are in MHz 
and may be specified as a floating-point number. The value is stored internally to 
the nearest kH z. The ordering of the clocks is important. It must match the 
order in which they are selected on the graphics board. M ultiple clocks lines may 
be specified. For boards with programmable clock chips, the ciockchip entry 
should be used instead of this A clocks entry is not mandatory for boards with 
non-programmable clock chips but is highly recommended because it prevents 
the clock probing phase during server startup. This clock probing phase can 
cause problems for some monitors 

T his optional entry is used to specify the clock chi p type on graphics boards that 
have a programmable clock generator. 0 nly a few X servers support program¬ 
mable clock chips. For details see the appropriate X server manual page. 

T his optional entry runs c o mma n d to set the clock on the graphics board i nstead of 
using the internal code. The command string must consist of the full pathname 
(and no flags). W hen using this option, a Clocks entry is required to specify 
which clock values are to be made available to the server (up to 128 docksmay 
bespecified). Theoptional t ext c i oc k value is to tell theserver that command must 
be run to restore the text-mode clock at server exit (or when VT switching), 
text ci ock must match one of the values in the Clocks entry. This parameter is 
required when the clock used for text mode is a programmable clock. 

The command is run with the real user's ID with stdin and stdout set to the 
graphics console device. T wo arguments are passed to the command. The first is 
the clock frequency in M Hzas a floating-point number andthesecond isthe 
index of the clock in theciocks entry. The command should return an exit status 
of 0 when successful and something in the range 1-254 otherwise. 

The comma nd is run when the initial graphics mode isset and when changing 
screen resolution with the hotkey sequences If the program fails at initialization, 
the server exits If it fails duringamode switch, the mode switch isaborted but 
the server keeps running. It is assumed that if the command fails, the clock has 
not been changed. 

Thisoptional entry allows the user to select certain options provided by the 
drivers. M ultiple option entries may be given. The supported values for 
opti onstri ng aregiven in the appropriate X server manual pages 
Thisoptional entry specifies the amount of video RAM that is installed on the 
graphics board. This is measured in kilobytes In most cases thisisnot required 
because theX server probes the graphics board to determine this quantity. 

T his optional entry specifies the base address of the video B10 S for the V G A 
board. This address is usually OxCOOOO, which is the default theX servers use. 
Some systems, particularly those with on-board VGA hardware, havetheBIOS 
located at an alternate address, usually OxE 0000. If your video BIOS is at an 
address other than OxC 0000, you must specify the base address i n the xF86Conf ig 
file. Note that someX servers don't access the BIOS at all and those that do only 
use the BIO S when searching for information during the hardware probe phase 
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MemBase baseaddress 

IOBase 

DAOBase baseaddress 

POSBase baseaddress 

COPBase baseaddress 

VGABase baseaddress 

Instance number 

Speedup sel ecti on 

S3MNAdj ust MN 
S3MClk clock 

S3RefClock cl ock 


This optional entry specifies the memory base address of a graphics board's linear 
frame buffer. This entry is only used by a few X servers, and the interpretation of 
this base address may be different for different X servers. Refer to the appropriate 
X server manual page for details. 

This optional entry specifies the 10 baseaddress. This entry is only used for a 
fewX servers Refer to the appropriate X server manual page for details 
This optional entry specifies the D AC baseaddress This entry is only used for a 
fewX servers Refer to the appropriate X server manual page for details 
This optional entry specifies the PO S base address. This entry is only used for a 
fewX servers Refer to the appropriate X server manual page for details 
This optional entry specifies the coprocessor base address. This entry is only used 
for a few X servers Refer to the appropriate X server manual page for details 
This optional entry specifies the VGA memory baseaddress This entry is only 
used for a few X servers Refer to the appropriate X server manual page for 
details. 

This optional entry specifies the instance (which indicates if the chip is 
integrated on the motherboard or on an expansion card). This entry is only used 
for a few X servers Refer to the appropriate X server manual page for details 
This optional entry specifies the selection of speedupsto be enabled. This entry 
isonlyusedforafewX servers. R efer to the appropriate X server manual page for 
details. 

Thisoptional entry is specific to the S3 X server. For details refer to the 
xf86_S3 (i) manual page 

Thisoptional entry is specific to the S3 X server. For details refer to the 
xf86_S3 (i) manual page 

Thisoptional entry is specific to the S3 X server. For details refer to the 
xf86_S3 (i) manual page 


The screen sections are used to specify which graphics boards and monitors are used with a particular X server and the 
configuration in which they are to be used. The entries available for this section are 

Driver d r i v e r - n a me E ach screen section must begi n with a Driver entry, and the d r i v e r - n a me given i n 

each screen section must be unique. The d r i ver - name determines which X server 
(or driver type within an X server when an X server supports more than one 
head) reads and uses a particular screen section. The driver names available are 
Accel 


Device d e vi c e-id 


ScreenNo sc mum 


SVGA 

VGA2 

VGA16 

Accel is used by all the accelerated X servers (see xF86_Accei(l)). Mono is used by 
the non-VGA mono drivers in the 2-bit and 4-bit X servers (see xF86_Mono(l) and 
xf86_vgai 6(1)). vga 2 and vgai6 are used by the VGA drivers in the 2-bit and 4-bit 
X servers svga is used by the xf86_svga X server. 

Specifies which graphics device description isto be used. 

Specifies which monitor description isto be used. 

Thisoptional entry overrides the default screen numbering in a multi-headed 
configuration. Thedefault numbering isdetermined by the ordering of the 
screen sections in thexF86Config file. T o override this, all relevant screen 
sections must havethisentry specified. 



BlankTime t i me 


SuspendTime t i me 


OffTime t i me 


Subsection Display 


Depth b p p 


Weight RGB 


Virtual x d i m y d i m 


Viewport x0 yO 


Modes modename ... 


Sdts the inactivity time-out for the blanking phaseof the screensaver, ti me isin 
mi nutes, and the default is 10. T his is equivalent to the X server's - s flag, and the 
value can be changed at runtime with xset(l). 

Sdts the inactivity time-out for the "suspend" phaseof the screensaver, t i me isin 
minutes, the default is 15, and it can be changed at runtime with xvidtune(l). This 
is only suitablefor VESA D PM S compatible monitors and is only supported 
currently by some X servers The "power_saver" option must be set for this to be 
enabled. 

Sdts the inactivity time-out for the "off" phase of the screensaver, ti me isin minutes, 
the default is 30 , and it can be changed at runtime with xvidtune(l). Thisisonly 
suitable for VESA D PM S compatible monitors and is only supported currently by 
someX servers The"power_saver" option must be set for this to be enabled. 

This entry isa subsection that is used to specify some display specific parameters. 
This subsection isterminated by an Endsubsection entry. For someX servers and 
drivers (those requiring a list of video modes), this subsection is mandatory. ForX 
servers that support multiple display depths, more than one Display subsec-tion can 
be present. W hen multiple Display subsections are present, each must have a unique 
Depth entry. The entries available for the Display subsection are 
Thisentry is mandatory when more than oneDispiay subsection is present in a 
screen section. When only oneDispiay subsection is present, it sped ties the default 
depth where the X server will run. When more than oneDispiay subsection is 
present, the depth determines which gets used by the X server. The subsection used 
isthe one matching thedepth at which theX server is run. N ot all X servers(or 
drivers) support more than one depth. Permitted valuesfor bpp ares, 15 , 16 , 24 , and 
32 . Not all X servers (or drivers) support all these values, bpp values of 24 and 32 are 
treated equivalently by those X servers that support them. 

This optional entry specifies the relative RGB weighting to be used for an X server 
running at 16bpp. This may also be specified from the command line (see 
xFree86(l)). Values supported by most 16bpp X servers are 555 and 565. For further 
details, refer to the appropriate X server manual page 
This optional entry specifies the virtual screen resolution to be used. *di mrnust be a 
multiple of either 8 or 16 for most color X servers and a multiple of 32 for the 
monochromeX server. The given value is rounded down if this is not the case For 
most X servers, video modes that are too large for the specified virtual size are 
rqected. I f this entry is not present, the virtual screen resolution is set to accommo¬ 
date all the valid video modes given in the Modes entry. SomeX servers do not 
support thisentry. Refer to the appropriate X server manual pages for details. 

This optional entry sets the upper-left corner of the initial display. This is only 
relevant when the virtual screen resolution is different from the resolution of the 
initial video mode If thisentry is not given, then the initial display is centered in the 
virtual display area. 

Thisentry is mandatory for most X servers, and it specifies the list of video modes to 
use. The video mode names must correspond to those specified in the appropriate 
Monitor section. MostX servers delete modes from this list that don't satisfy various 
requirements T hefirst valid mode in this list isthe default display mode for startup. 
The list of valid modes is converted internally into a circular list. It is possibleto 
switch to the next mode with CtrUAIt+Keypad Plus and to the previous mode with 
Ctrl+Alt+Keypad M inus. 


InvertVCLK 
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This optional entry isspecific to the S3 server only. It can be used to change the 
default Eariysc setting for individual modes This setting can affect screen wrapping. 
If "modename" isthesetting applies to all modes unless overridden by later entries 
This optional entry isspecific to the S3 server only. It can be used to change the 
default blank delay settingsfor individual modes. Thiscan affect screen wrapping, 
vai uei and vai je 2 must be integers in the range 0-7. If "modename ■ is "".thesetting 
applies to all modes unless overridden by later entries. 

This optional entry sets the default root visual type Thiscan also be specified from 
the command line (see xserver(l)). T he visual types avai lablefor 8bpp X servers are 
(default is Pseudocolor): 

StaticGray 
Grayscale 
StaticColor 
Pseudocolor 
TrueColor 
DirectColor 

The visual type avai lablefor the 16bpp and 32bppX servers is TrueColor. 

The visual type available for the lbpp X server is StaticGray. 

The visual types available for the 4bpp X server are (default ispseudocoior): 
StaticGray 
Grayscale 
StaticColor 
Pseudocolor 

This optional entry allows the user to select certain options provided bythedrivers 
M ultiple option entries can be given. The supported values for opti on-stri ng are 
given in the appropriate X server manual pages 

This optional entry allows the "black” color to be specified. Thisisonly supported 
with theVGA2 driver in thexF86_Mono server (for details see xF86jiono(l)). 

This optional entry allows the "white" color to be specified. Thisisonly supported 
with theVGA2 driver in thexF86_Mono server (for details see xF86_Mono(l)). 

For an example of an xF86Config file, see the file installed as<xRoot>/iib/xn/xF86Config.eg. 

FILES 

/etc/XF86Config 

<XRoot>/lib/X11/XF86Config. hostname <XRoot>/lib/X11/XF86Config 

Note that <xRoot> refers to the root of the X11 install tree. 

SEE ALSO 

X(l), Xserver(l), XFree86(l), XF86_SVGA(1), XF86_VGA16(1), XF86Jlono(l), XF86_S3(1), XF86_8514(1), XF86Jlach8(l), 
XF86_Mach32(l), XF86_P9000(1), XF86_AGX(1), XF86_W32<1) 

AUTHORS 

Refer to the xFree86(l) manual page. 


EarlySC modename 011 

BlankDelay modename »aIue 1 vaiue2 

Visual vi s u a I - name 


Option opt ionstring 

White red green blue 
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intro 

intro— Introduction to game. 

DESCRIPTION 

This chapter decri be all the game and funny little programs avail able on the system. 

AUTHORS 

Look at the header of the manual page for the authors and copyright conditions Note that these can be different from page 
to page! 

Linux, 24 July 1993 


banner 

banner— Print large banner on printer. 

SYNOPSIS 

/usr/games/banner [ -wn ] message ... 

DESCRIPTION 

banner printsa large, high-quality banner on the standard output. If the message is omitted, itpromptsforand reads oneline 
of its standard input. If -w is given, the output is scrunched down from a width of 132 to n, suitable for a narrow terminal. If 
n is omitted, it defaults to se. 

The output should be printed on a hard-copy device, up to 132 columns wide with no breaks between the pages. The 
volume is great enough that you might want a printer or a fast hard-copy terminal, but if you are patient, a decwriter or 
other 300 baud terminal will do. 

BUGS 

Several ASCII characters are not defined, notably <, >,[,], \,|, and Also, the characters", ', and & are funny¬ 
looking (but in a useful way). 

The -w option is implemented by skipping some rows and columns Thesmaller it gets, thegrainier the output. Sometimes it 
runs letters together. 

AUTHOR 

M ark H orton 

6Junel993 


ddate 

ddate- Converts boring normal datesto fun D iscordian dates 

SYNOPSIS 





ddate 


DESCRIPTION 

ddate prints the date in Discordian date format. 

AUTHOR 

Druel the Chaotic, a.k.a. Jeremy Johnson (mpython@gnu.ai.mit.edu). Modifications for UN IX by Lee H arvey Oswald Smith, 
K.S.C. Five tons of flax. 

55 Confudon 3160 
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intro 

intro— Introduction to miscellany section. 

DESCRIPTION 

This chapter describes miscellaneous things such asnroff macro packages, tables, C header files, the file hierarchy, general 
concepts, and other things that don't fit anywhere else. 

AUTHORS 

Look at the header of the manual page for the authors and copyright conditions Note that these can be different from page 
to page! 

Linux, 23 April 1993 


ascii 

ascii-The ASCI I character sdt encoded in octal, decimal, and hexadecimal 


DESCRIPTION 

The followi ng table contai ns the 128 
C program ‘\X’ escapes are noted. 


Oct Dec Hex 

MO 0 OcT 

001 1 01 

002 2 02 

003 3 03 

004 4 04 

005 5 05 

006 6 06 

007 7 07 

010 8 08 

011 9 09 

012 10 0A 

013 11 0B 

014 12 0C 

015 13 0D 

016 14 OE 

017 15 OF 

020 16 10 

021 17 11 

022 18 12 

023 19 13 

024 20 14 

025 21 15 

026 22 16 


characters 


Char Oct Dec 

NUL ‘\0’ 100 

SO H 101 65 

STX 102 66 

ETX 103 67 

EOT 104 68 

ENQ 105 69 

ACK 106 70 

BEL V 107 71 

BS‘\b’ 110 72 

HT‘\t’ 111 73 

LF ‘\n’ 112 74 

VT ‘\v’ 113 75 

FF '\f' 114 76 

C R V 115 77 

50 116 78 

51 117 79 

DLE 120 80 

DC1 121 81 

DC2 122 82 

DC3 123 83 

DC4 124 84 

NAK 125 85 

SYN 126 86 


Hex 


Char 


41 A 

42 B 

43 C 

44 D 

45 E 

46 F 

47 G 

48 H 

49 I 

4A J 

4B K 

4C L 

4D M 

4E N 

4F 0 

50 P 

51 Q 

52 R 

53 S 

54 T 

55 U 

56 V 



ascii 


Oct Dec Hex 

~027 23 17 

030 24 18 

031 25 19 

032 26 1A 

033 27 IB 

034 28 1C 

035 29 ID 

036 30 IE 

037 31 IF 

040 32 20 

041 33 21 

042 34 22 

043 35 23 

044 36 24 

045 37 25 

046 38 26 

047 39 27 

050 40 28 

051 41 29 

052 42 2A 

053 43 2B 

054 44 2C 

055 45 2D 

056 46 2E 

057 47 2F 

060 48 30 

061 49 31 

062 50 32 

063 51 33 

064 52 34 

065 53 35 

066 54 36 

067 55 37 

070 56 38 

071 57 39 

072 58 3A 

073 59 3B 

074 60 3C 

075 61 3D 

076 62 3E 

077 63 3F 


Char Oct 

~ETB 127" 

CAN 130 

EM 131 

SU B 132 

ESC 133 

FS 134 

GS 135 

RS 136 

US 137 

SPACE 140 

! 141 

" 142 

# 143 

$ 144 

% 145 

& 146 

147 

( 150 

) 151 


* 152 

+ 153 

154 

155 

156 

/ 157 

0 160 

1 161 

2 162 

3 163 

4 164 

5 165 

6 166 

7 167 

8 170 

9 171 

: 172 

; 173 

< 174 

= 175 

> 176 

? 177 


Dec 

~87~ 

88 

89 

90 

91 

92 

93 

94 

95 

96 

97 

98 

99 

100 
101 
102 

103 

104 

105 

106 

107 

108 

109 

110 
111 
112 

113 

114 

115 

116 

117 

118 

119 

120 
121 
122 

123 

124 

125 

126 
127 


Hex Char 

~57 W 

58 X 

59 Y 

5A Z 

5B [ 

5C YW 

5D ] 

5E 

5F 

60 

61 a 

62 b 

63 c 

64 d 

65 e 

66 f 

67 g 

68 h 

69 i 

6A j 

6B k 

6C I 

6D m 

6E n 

6F o 

70 p 

71 q 

72 r 

73 s 

74 t 

75 u 

76 v 

77 w 

78 x 

79 y 

7A z 

7B { 

7C | 

7D } 

7E 

7F DEL 
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HISTORY 

An ascii manual page appeared in version 7 AT&T UNIX. 

SEE ALSO 

iso_8859_1 (7) 

L inux 


bootparam 

bootparam— Introduction to boot-time parameters of the Linux kernel. 

DESCRIPTION 

The Linux kernel accepts certain command-line options or boot-time parameters at the moment it isstarted. In general,this 
is used to supply the kernel with information about hardware parameters that the kernel would not beableto determineon 
its own, or to avoid or override the values that the kernel would otherwise detect. 

When the kernel is booted directly by the BIOS (say, from a floppy to which you copied a kernel using cp zimage /dev/fdo), 
you have no opportunity to specify any parameters To take advantage of this possibility, you have to use software that is able 
to pass parameters such asLILO or loadlin. For a few parameters one can also modify the kernel image itself, using rdev; see 
rdev{8) for further details 

TheLILO program (Linux LOader) written by Werner Almesberger is the most commonly used. It has the ability to boot 
various kernels and stores the configuration information in aplain text file (Seenio(8) and nio.conf (5).) LILO can boot 
DOS, OS/2, Linux, FreeBSD, and so on and is quite flexible. 

The other commonly used Linux loader is loadlin, which is a DOS program that has the capability to launch a Linux kernel 
from the DOS prompt (with bootargs) assuming that certain resources are available. This is good for people who want to 
launch Linux from DOS. 

It isalso very useful if you have certain hardware that relies on the supplied DOS driver to put the hardware into a known 
state. A common example is SoundBlaster-compatible sound cards that requi re the DOS driver to twiddle a few mystical 
registers to put the card into a SB-compatible mode. Booting DO S with the supplied driver and then loading Linux from the 
DOS prompt with loadlin avoids the reset of the card that happens if one reboots instead. 

THE ARGUMENT LIST 

M ost of the boot args take the form of 

n a me [ =* a I u e _1 ] [ ,v a I u e _ 2 ]... [ , v a[ u e _ 11 ] 

n a me is a unique keyword that is used to identify what part of the kernel the associated values (if any) are to be given to. 

M ultiple boot args are just a space-separated list of the preceding format. Note the limit of 11 is real because the present code 
handles only 11 comma-separated parameters per keyword. (H owever, you can reuse the same keyword with up to an 
additional 11 parameters in unusually complicated situations, assuming the setup function supports it.) 

M ost of the sorting occurs in linux/init/main. c. First, the kernel checks to see if the argument is any of the special 
arguments root=, ro, rw, or debug. The meaning of these special arguments is described later in the document. 

Then, it walks a list of setup functions (contained in thebootsetups array) to see if the specified argument string (such asfoo) 
is associated with a setup function (too_setup( )) for a particular device or part of the kernel. If you passed the kernel the line 
f 00=3,4,5,6, then the kernel searches thebootsetups array to see if too is registered. If it is, it calls the setup function 
associated with too (foo_setup()) and hands it the arguments 3,4,5, and 6 as given on the kernel command line. 

Anything of the form foo=barthat is not accepted as a setup function as described is then interpreted as an environment 
variable to beset. A (useless?) exampleisto useTERM=vti0o as a boot argument. 
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Any remaining arguments that were not picked up by the kernel and were not interpreted as environment variables are then 
passed onto process one which is usually the init program. The most common argument that is passed to theinit process is 
the word single, which instructs init to boot the computer in single-user mode and not launch all the usual daemons Check 
the manual page for the version of init installed on your system to see what arguments it accepts 

GENERAL NON-DEVICE-SPECIFIC BOOTARGS 

no387 

Somei387 coprocessor chips have bugs that show up when used in 32-bit protected mode 

For example, some of the early U LSI-387 chips cause solid lockupswhile performing floating-point calculations Using the 
1 no387 ■ boot arg causes Linux to ignore the maths coprocessor even if you haveone Of course you must then have your 
kernel compiled with math emulation support! 

no-hlt 

Some of the early i486D X-100 chips have a problem with the hit instruction in that they can't reliably return to operating 
mode after this instruction isused. Using the 'no-hit 1 instruction tells Linux to just run an infinite loop when there is 
nothing else to do and to not halt the CPU. This allows people with these broken chips to use Linux. 

root=... 

This argument tells the kernel what device is to be used as the root filesystem whilebooting. The default of thissetting is 
determined at compile time and usually is the value of the root device of the system that the kernel was built on. To override 
this value and select the second floppy drive as the root device one uses 'root=/dev/fdi '. (The root device can also beset 
Using rdev(8).) 

The root device can be specified symbolically or numerically. A symbolic specification hastheform /dev/xxYN, where xx 
designatesthedevicetype (hd for ST-506-compatible hard disk with y in a-t»; sd for SC Sl-compatible disk with y in a-e; xd 
for XT-compatible disk with y either a or b; fd for floppy disk with y the floppy drive number- f da is the D 0 S A: drive and 
fdi is B:), y isthe driver letter or number, andN isthe number of the partition on this device (absent in the caseof floppies). 
N otethat this has nothing to do with the designation of these devices on your filesystem. The /dev/ part is purely conven¬ 
tional. 

The more awkward and less portable numeric specification of the previous possible root devices in major/minor format is 
also accepted. (For example /dev/sda3 ismajor 8, minor 3, so you can use root=ax803 as an alternative.) 

r o and r w 

The ro option tells the kernel to mount the root filesystem as readonly so that filesystem consistency check programs (fsck) 
can do their work on a quiescent file system. N o processes can write to files on the filesystem in question until it is re¬ 
mounted as read/write capable, such as by mount -w -n -o remount /. (See also mount(8).) 

The rw option tells the kernel to mount the root filesystem read/write. Thisisthe default. 

The choice between read-only and read/write can also besetusingrdev(8). 


Kernel messages are handed off to the kernel log daemon kiogd so that they can be logged to disk. M essages with a priority 
above consoie_iogievei are also printed on the console (For these levels, see<iinux/kernei.h>.) By default, this variable is sdt 
to log anything more important than debug messages. This boot argument causes the kernel to also print the messages of 
debug priority. The console log level can also beset at runtime via an option to kiogd. See kiogd(8). 


This is used to protect I/O port regions from probes The form of the command is 

reserved obase,extent[,iobase,extent ]... 
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In some machines, it might be necessary to prevent device drivers from checking for devices (auto-probing) in a specific 
region. This may be because of hardware that reacts badly to the probing, hardware that would be mistakenly identified, or 
hardware you don't want the kernel to initialize 

The reserve boot-time argument specifies an I/O port region that shouldn't be probed. A device driver does not probe a 
reserved region unless another boot argument explicitly specifies that it do so. 

For example, the boot line 

reserve=0x300,32 blah=0x300 

keeps all device drivers except the driver for blah from probing 0x300-0x31f. 

ramdi sk=. .. 

This option is obsolete since Linux 1.3.48 or so. It specifies the size in kilobytesof the optional RAM disk device. For 
example, if one wants to have a root filesystem on a 1.44M B floppy loaded into the RAM disk device they use 

ramdisk=1440 

This option is sdt at compile time (default is no RAM disk), andean be modified using rdev(8). 


The BIOS call defined in the PC specification that returns the amount of installed memory wasonly designed to be able to 
report up to 64M B. Linux uses this BIOS call at boot to determine how much memory is installed. If you have more than 
64M B of RAM installed, you can use this boot arg to tell Linux how much memory you have. The value is in decimal or 
hexadecimal (prefix Ox), and the suffixes k (times 1024) or m (times 1048576) can be used. The following quote from Linus 
describes the use of the mem= parameter: 

"The kernel will accept any mem=** parameter you give it, and if it turns out that you lied to it, it will crash horribly sooner or 
later. The parameter indicatesthe highest addressable RAM address,so 'mem= 0 xi 000000 1 means you have 16M B of memory, 
for example. Fora96M B machine this would be 11611 = 0 x 6000000 . 

N 0 T E: Some machi nes might use the top of memory for B10 S cachi ng or whatever, so you might not actually have up to 
thefull 96M B addressable. The reverse is also true: Some chipsets will map the physical memory that is covered by the BIOS 
area into the area just past the top of memory, so the top-of-mem might actually be 96M B + 384KB, for example. If you tell 
Linux thatithasmore memory than it actually does have, bad things will happen: maybe not at once, but surely eventually." 


Since 2.0.22, a reboot is by default a cold reboot. Thiscommand-lineoption changes back to the old default, a warm reboot. 

B00TARGUMENTSFOR SCSI DEVICES 

General notation for thissection: 

iobase— the first I/O port that the SC SI host occupies These are specified in hexadecimal notation and usually liein the 
rangefrom 0x200 to 0x3ff. 

irq— the hardware interrupt that the card is configured to use V alid values are dependent on the card in question but are 
usually 5 , 7 , 9 , 10 , 11 , 12 , and 15 . The other values are usually used for common peripherals such as IDE hard disks floppies 
serial ports and so on. 

scsi-id— the ID that the host adapter uses to identify itself on the SC SI bus O nly some host adapters allow you to change 
this value because most have it permanently specified internally. The usual default value isz, but the Seagate and Future 
D omain T M C -950 boards use 6. 

parity- whether the SC SI host adapter expects the attached devices to supply a parity value with all information exchanges 
Specifying a 1 indicates parity checking is enabled, and a 0 disables parity checking. Again, not all adapters support selection 
of pari ty behavior as a boot argument. 
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max_scsi_luns=... 

A SCSI device can havea number of subdevices contained within itself. The most common example isoneof the new SCSI 
CD-ROMs that handle more than one disk at a time. Each CD is addressed as a Logical Unit Number (LUN) of that 
particular device M ost devices, such as hard disks and tape drives, are only one device and are assigned to LU N 0 . 

Some poorly designed SCSI devices cannot handle being probed for LU N snot equal to 0 . Therefore, if the compile-time flag 
CONFIG scsi multi lun is not set, newer kernels by default only probe LU N 0 . 

Tospecify thenumber of probed LUNsat boot,oneenters max scsi iuns=n as a boot arg, where n isa number between 1 
and 8. To avoid problems as described, one uses n=i to avoid upsetting such broken devices 

SCSI TAPE CONFIGURATION 

Some boot-time configuration of the SC SI tape driver can be achieved with the following: 

st=buf _si ze [, write, threshold!, max. bufsj] 

The first two numbers are specified in units of kilobytes T he default buf. si ze is 32KB, and the maximum size that can be 
specified isa ridiculous 16384KB. The wr i te.t hr es hoi d isthe value at which the buffer is committed to tape with a default 
value of 30KB. The maximum number of buffers varies with thenumber of drives detected and has a default of two. A 
sample usage is 


Full details can be found in the readme, st file that isin the scsi directory of the kernel source tree. 

ADAPTEC AHA151X, AHA152X, AIC6260, AIC6360, SB16-SCSI CO NFIGU RATIO N 

The aha numbers refer to cards and the aic numbers refer to the actual SCSI chip on these types of cards including the 
SoundBlaster-16 SCSI. 

The probe code for these SC SI hosts looks for an installed BIOS, and if none is present, the probe will not find your card. 
Then you must use a boot arg of the form: 

aha 152 x=i obase[,i rq[,scsi-id[,reconnect [.parity]]]] 

If thedriver was compiled with debugging enabled, a sixth value can be specified to set the debug level. 

All the parameters are as described at the top of this section, and the reconnect value allows de/ice disconnect/reconnect if a 
nonzero value is used. A sample usage is as follows 

ahal 52 x= 0 x 340 , 11 , 7,1 

Note that the parameters must be specified in order, meaning that if you want to specify a parity setting, then you must 
specify an iobase,irq,scsi-id, and reconnect valueaswell. 

ADAPTEC AHA154X CONFIGURATION 

Theahal542 series cards have an i82077 floppy controller on board, whereas the ahal540 series cards do not. These are bus¬ 
mastering cards and have parameters to set the "fairness" that is used to share the bus with other devices. The boot arg looks 
likethefollowing: 

ahal 542 =i obase[,buson,busoff [, d ma s p e e d ] ] 

Valid i obase values are usually one of 0x130,0x134,0x230,0x234,0x330, or 0x334. C lone cards may permit other values. 

The bus on and bus of f values refer to the number of microseconds that the card dominates the ISA bus. The defaults are 11 us 
on and4us off so that other cards (such as an ISA LANCE Ethernet card) have a chance to get access to the ISA bus 
T he d mas peed value refers to the rate (in M B/s) at which the DM A (Direct M emory Access) transfers proceed. The default is 
5M B/s. N ewer revision cards allow you to select this value as part of the soft-configuration; older cards use jumpers You can 
use values up to 10M B/s, assuming that your motherboard is capable of handling it. Experiment with caution if using values 
over 5M B/s. 
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ADAPTEC AHA274X, AHA284X, AIC7XXX CONFIGURATION 

These boards can accept an argument of the form: 

aic7xxx=ext ended ,no_reset 

The extended value, if nonzero, indicates that extended translation for large disks is enabled. The no. reset value, if nonzero, 
tells the driver not to reset the SC SI bus when setting up the host adapter at boot. 

BUSLOGIC SCSI H0STS C0NFIGU RATION (buslogiC=) 

At present, the buslogic driver accepts only one parameter, the I/O base. It expects that to be one of the following valid 
values: 0x130,0x134,0x230,0x234,0x330, or 0x334. 

FUTURE DOMAIN TMC-8XX,TMC-950 CONFIGURATION 

If your card is not detected at boot time you must use a boot arg of the form 

tmc8xx=mem_base,i r q 

Themem.base value isthevalueof the memory-mapped I/O region that the card uses This is usually one of thefollowing 
values: 0x08000,0xca00@, 0x00000,0x00000,0x110000, or 0xde000. 

PRO AUDIO SPECTRUM CONFIGURATION 

ThePAS16 uses an NC5380 SCSI chip, and newer models support jumperless configuration. The boot arg is of the form 

pasl6=i 0bas e ,i rq 

The only difference isthat you can specify an IRQ value of 255, which tellsthe driver to work without using interrupts, 
albeit at a performance loss. Thei obase is usually 0x388. 

SEAGATE ST-OX CONFIGURATION 

If your card is not detected at boot time you must use a boot arg of the form 

st0x=mem_base ,i rq 

Thememjase value isthevalueof the memory-mapped I/O region that thecard uses This is usually oneof thefollowing 
values 0xc8000, 0xca000, 0XCC000, 0xce000, 0xdc000, Or 0xde000. 

TRANTORT128 CONFIGURATION 

These cards are also based on theNCR5380 chip and accept thefollowing options 

t128=mem_base ,i r q 

The valid values for mem. base are as follows 0x00000,0x08000,0xdc000, and nxmm. 

CARDSTHAT DON'T ACCEPT BOOT ARGS 

At present, thefollowing SCSI cards do not make use of any boot-time parameters. In some cases you can hard-wi re values 
by directly editing the driver itself, if required. 

Always IN 2000, Adaptec ahal740, EAT A-D M A, EAT A-PIO, Future D omain 16xx, N C R5380 (generic), N C R53c7xx to 
NCR53c8xx, Qlogic, Ultrastor (including u?4f), and Western Digital wd7000. 

HARD DISKS 

IDE DISK/CD-ROM DRIVER PARAMETERS 

The ID E driver accepts a number of parameters, which range from disk geometry specificationsto support for broken 
controller chips. D rive specific options are specified by using hdx= with x in a-h. 

Non-drive-specific optionsare specified with the prefix hd=. Note that using a drive-specific prefix for a non-drive-specific 
option will still work, and theoption will just be applied as expected. 
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Also note that hd= can be used to refer to the next unspecified drive in the (a.h) sequence. For thefollowing discussions, 

the hd= option will be cited for brevity. See the file readme, ide in unux/drivers/biockfor more details. 

TH Ehd=cyls,heads,sects[,wpcom[,irq] ] OPTIONS 

These options are used to specify the physical geometry of the disk. Only thefirst three values are required. The cylinder, 
head, and sectors values are those used by fdisk. The write precompensation value is ignored for ID E disks. The IRQ value 
specified is the IRQ used for the interface that the drive resides on and is not really a drive-specific parameter. 

THE hd=serialize OPTION 

The dual IDE interface CM D-640 chip is broken as designed such that when drives on the secondary interface are used at 
the same time as drives on the primary interface, it will corrupt your data. Using this option tells the driver to make sure that 
both interfaces are never used at the same time 

THE hd=dtc2278 OPTION 

This option tells the driver that you have a DTC-2278D IDE interface. The driver then tries to do DTC-specific operations 
to enable the second interface and to enable faster transfer modes 

THE hd=noprobe OPTION 

Do notprobeforthisdrive. Thefollowing line 

hdb=noprobe hdb=1166,7,17 

disables the probe but still specifies the drive geometry so that it is registered asavalid block device and hence usable. 

THE hd=nowerr OPTION 

Some drives apparently have the wrerr stat bit stuck on permanently. Thisenables a work-around for these broken devices 
THE hd=cdrom OPTION 

This tells the IDE driver that there is an ATAPI compatible CD-ROM attached in place of a normal IDE hard disk. In most 
cases, theCD-ROM is identified automatically, but if it isn't, then this might help. 

STAN DARD ST-506 DISK D RIVER 0 PTIO N S (hd=) 

T he standard disk driver can accept geometry arguments for the disks similar to the ID E driver. N ote however that it only 
expects three values (c/h/s); any more or any less and it will silently ignore you. Also, it only accepts hd= as an argument; hda= 
and so on are not valid here. The format is as follows: 

hd=cyI s ,heads,sects 

If there are two disks installed, the preceding line is repeated with the geometry parameters of the second disk. 

XT D ISK D RIVER 0 PTIO N S (xd=) 

If you are unfortunate enough to be using one of these old 8-bit cards that move data at a whopping 125K B/s, then here is 
the scoop. If the card is not recognized, you must use a boot arg of theform 

Thetype value specifiesthe particular manufacturer of the card, and you use one of thefollowing: u=generic, i=DTC, 2 , 3, 
4=Western Digital, 5,6 , 7=Seagate, or 8=0 M Tl. The only difference between multiple types from the same manufacturer is 
the BIO S string used for detection, which is not used if thetype is specified. 

Thexd_setupo function does no checking on the values and assumes that you entered all four values. Don't disappoint it. 

FI ere is a sample usage for a WD1002 controller with the BIOS disabled or removed, using the default XT controller 
parameters: 


xd=2,5,0x320,3 
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CD-ROMS (NON-SCSI/ATAPI/IDE) 

THE AZTECH INTERFACE 

T he syntax for this type of card is 

aztcd=i obase [,magi c_number ] 

If you set the magi c. number to 8x79, the driver will run anyway in the event of an unknown firmware version. All other values 
are ignored. 

THECDU-31A AND CDU-33ASONY INTERFACE 

ThisCD-RO M interface isfound on some of the Pro Audio Spectrum sound cards and other Sony supplied interface cards 
The syntax is as follows 

cdu31a=i obase, [i r q [,is_pas_card ]] 

Specifying an IRQ value of 0 tellsthe driver that hardware interrupts aren't supported (as on some PAS cards). If your card 
supports interrupts, you should use them because they cut down on the CPU usage of the driver. 

The i s. pas, card should be entered as pas if using a Pro Audio Spectrum card; otherwise, it should not be specified at all. 

THE CDU-535 SONY INTERFACE 

The syntax for this CD-ROM i nterface i s 
sonycd535=i obase [,i r q ] 

A 0 can be used for the I/O base as a placeholder if you want to specify an IRQ value. 

THE GOLDSTAR INTERFACE 

The syntax for this CD-ROM i nterface i s 


THE MITSUMI STANDARD INTERFACE 

ThesyntaxforthisCD-ROM interfaceis 

mcd=i obase ,[i rq [,wai t val ue ]] 

Thewai t.vai ue isused as an internal time-out value for people who are having problems with their drive and mayor may 
not be implemented depending on a compile-time #define. The M itsumi FX400 is an IDE/ATAPI CD-ROM player and 
does not use the mcd driver. 

THEMITSUMlXA/MULTISESSION INTERFACE(mcdx=) 

At present, this experimental driver has a sdtup function, but no parameters are implemented (as of 1.3.15). Thisisfor the 
same hardware as previously described, but the driver has extended features. 

THE OPTICS STORAGE IN TERFACE 

T he syntax for this type of card is 

optcd=i obase 

THE PH HUPS CM 206 INTERFACE 

T he syntax for this type of card is 

cm206=[i obase ][ ,i rq ] 

The driver assumes numbers between 3 and 11 are IRQ values and numbers between 0x300 and 0x370 are I/O ports, so you 
can specify one or both numbers, in any order. It also accepts cm 206 =auto to enable autoprobing. 
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THE SANYO INTERFACE 

T he syntax for this type of card is 

sjcd=i obase [,i rq [,dma.channel ]] 

THE SOUNDBLASTER PRO INTERFACE 

T he syntax for this type of card is 

sbpcd=i obase .type 

type is one of the following (case-sensitive) strings: SoundBlaster, LaserMate, orsPEA. The I/O baseisthatoftheCD-ROM 
interface and not that of the sound portion of the card. 

ETHERNET DEVICES 

D ifferent drivers use different parameters, but they all at least share having an I RQ, an I/O port base value and a name I n 
its most generic form, it looks something like this: 

ether=irq,i obas e [ .par a m_ 1 [ .par a m_2,.. .pa r am.8 ] ] ,name 

Thefirst non-numeric argument is taken as the name. Theparam.n values (if applicable) usually have different meanings for 
each different card or driver. T ypical pa r am.n values are used to specify things such as shared memory address, interface 
selection, DMA channel, and the like. 

The most common use of this parameter is to force probing for a second dthercard because the default isto only probe for 
one Thiscan be accomplished with asimple 

ether=0,0,eth1 

N ote that the values of 0 for the I RQ and I/O base in the example tell the drivers to autoprobe 
The Ethernet HowTo has extensive documentation on using multiple cards and on the card-specific or driver-specific 
implementation of theparam.n values where used. Interested readers should refer to the section in that document on their 
particular card. 

THE FLOPPY DISK DRIVER 

There are many floppy driver options,and they are all listed in readme, fd in linux/drivers/biock.Thisinformation istaken 
directly from that file. 

floppy=mask, allowed drive mask 

Sets the bitmask of allowed drives to mask. By default, only units 0 and 1 of each floppy controller are allowed. T his is done 
because certain non-standard hardware (ASUS PCI motherboards) mess up the keyboard when accessing units 2 or 3. This 
option is somewhat obsolete because of the cmos option. 

floppy=all drives 

Sets the bitmask of allowed drives to all drives Use this if you have more than two drives connected to a floppy controller. 

floppy=asus_pci 

Sets the bitmask to allow only units 0 and 1 (the default). 

floppy=daring 

T ells the floppy driver that you havea well-behaved floppy controller. This allows more efficient and smoother operation but 
may fail on certain controllers. Thiscan speed up certain operations. 

floppy=0,daring 

Tel Is the floppy driver that your floppy controller should be used with caution. 
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floppy=one_fdc 

T ells the floppy driver that you haveonly onefloppy controller (default), 

f loppy=two_f dc OR f loppy=address, twof dc 

T ells the floppy driver that you have two floppy controllers. The second floppy controller is assumed to be at address. If 
address is not given, 0 x 370 is assumed. 

floppy=thinkpad 

T ells the floppy driver that you have a Thinkpad. Thinkpads use an inverted convention for the disk change line, 

floppy=0,thinkpad 

Tells the floppy driver that you don't have a Thinkpad. 

floppy=drive,type, cmos 

Sets the cmos type of drive to type. Additionally, this drive isallowed in the bitmask. This is useful if you have more than two 
floppy drives (only two can be described in the physical cmos), or if your BIOS uses non-standard cmos types. Setting the cmos 
to 0 for the first two drives (default) makes the floppy driver read the physical cmos for those drives. 

floppy=unexpected_interrupts 

Print a warning message when an unexpected interrupt is received (default behavior) 

floppy=no unexpected_interrupts ORfloppy=L40SX 

Don't print a message when an unexpected interrupt is received. This is needed on IBM L40SX laptops in certain video 
modes. (There seems to bean interaction between video and floppy. The unexpected interrupts only affect performance and 
can safely be ignored.) 

THE SOUND DRIVER 

The sound driver can also accept boot argsto override the compiled in values. Thisisnot recommended because it israther 
complex. It isdescribed in the Readme. Linux file in unux/drivers/sound. It accepts a boot argoftheform 
sound=dei/i cel[,devi ce2[,device3. ..[,devi cell ]]] 

E ach d e v i c e n value is of theformat oxt a a a 1 d and the bytes are used asfollows 
t— device type i=fm, 2=sb, 3=pas, 4=gus, 5=mpu40i, 6=sbi6 , and 7=sbi6-mpu40i 
aaa —I/O addressin hex 
1 — interrupt line in hex (10=0,11 =b,...) 
d— DMA channel 

Asyoucan see, it gets pretty messy, and you are better off to compilein your own personal values as recommended. Using a 
boot arg of sound =0 disables the sound driver entirely. 

THE BUS MOUSE DRIVER (bmouse=) 

The busmousedriver only acceptsone parameter, the hardware IRQ value to be used. 

AUTHORS 

LinusTorvalds (and many others) 

SEE ALSO 

klogd(8), lilo.conf(5), lilo(8), mount(8), rdev(8) 

This man page was derived from the Boot Parameter HOWTO (version 1.0.1) written by Paul Gortmaker. More informa¬ 
tion can be found in this (or a more recent) HOWTO. 


Linux 1.3.19,15 August 1995 
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groff_me 

groff_me— troff macrosfor formatting papers 

SYNOPSIS 

groff_me [options [file ... 
troffjne [ opti ons [file ... 


DESCRIPTION 

This manual page describes the GN U version ofthe_me macros, which is part of thegroff document formatting system. 
This version can be used with both GNU troff and UN IX troff. This package of troff macro definitions provides a canned 
formatting facility for technical papersin variousformats. 

The macro requests are defined as follows M any troff requests are unsafe in conjunction with this package; however, these 
requests can be used with impunity after thefirst .pp: 


.bp 
.br 
.sp n 


.ul n 


Begin new page 
Break output line here 
Insert n spacing lines 

Linespacing; n=i single, n=2 double space 
N o alignment of right margin 
Center nextn lines 
Underline next n lines 


0 utput of the pic, eqn, refer, and tbi preprocessors is acceptable as input. 

FILES 

/usr/lib/groff/tmac/tmac.e 


SEE ALSO 

groff(l), gtroff (1), _me Reference M anual, Eric P. Allman, Writing Papers with Groff Using _me 

REQUESTS 

This list is incomplete; seethe_me Reference M anual for interesting details 


Request 

Initial Value 

Cause Break 

Explanation 

■ (c 


Yes 

Begin centered block. 

■ (d 


No 

Begin delayed text. 

■ (f 


No 

Begin footnote 

■(1 


Yes 

Begin list. 

■ (q 


Yes 

Begin major quote. 

.(X X 


No 

Begin indexed item in index*. 



No 

Begin floating keep. 



Yes 

End centered block. 

. )d 


Yes 

End delayed text. 

■ )f 


Yes 

End footnote 

■)1 


Yes 

End list. 

■ )q 


Yes 

End major quote 


continues 
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Request Initial Value CaussBreak 

~x - Yes 

■) z - Yes 

.++## - No 


.EN 

■ EQ * y 


Yes 

Yes 

Yes 

Yes 

Yes 


GE 

GS 

PE 

PS 

TE 

TH 

TS 


Yes 

Yes 

Yes 

Yes 

Yes 

Yes 

Yes 

No 


Yes 


.ef 1 x 1 y 1 z 


.fo 'x 'y 'z ' 


.hi 


■ip * y 


No 

No 

No 


No 

No 


Yes 

No 

Yes 

No 

No 

No 

No 

No 

No 

Yes 

No 

Yes 


Explanation 
End index item. 

End floating keep. 

Define paper section. 

m defines the part of the paper and can bee 
(chapter), a (appendix), p (preliminary, such as 
abstract, table of contents, and so on), b (bibliogra¬ 
phy), rc (chapters renumbered from page one each 
chapter), or ra (appendix renumbered from page 
one). 

Begin chapter (or appendixand so on asset by.++). 
T is the chapter title. 

0 ne column format on a new page 
Two column format. Equation number isy. 

Space after equation produced by eqn or neqn. 
Precede equation; break out and add space. 

The optional argument x may be i to indent 
equation (default), l to left-adjust the equation, ore 
to center the equation. 

End gremlin picture. 

Begin gremlin picture. 

End pic picture. 

Begin pic picture. 

End table 

End heading section of table. 

Begin table; if x is h, table has repeated heading. 
Print x in boldface; if no argument switch to 
boldface. 

Augments the base indent by n. 

This indent is used to set the indent on regular text 
(like paragraphs). 

Begin new column. 

Print x in bold italics (no fill only). 

Begin bulldted paragraph. 

Print x in a box (no fill only). 

Set even footer to x y z. 

Set even header to x y z. 

Set footer to x y z. 

Suppress headers and footers on next page 
Set header to x y z. 

Draw a horizontal line. 

Italicize x; if x is missing, italic text follows. 

Start indented paragraph with hanging tag x. 
Indentation isy ens(default is 5 ). 
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Request 

Initial Value 

Cause Break 

Explanation 

■ ip 

Yes 

Yes 

Start left-blocked paragraph. 

■ np 

1 

Yes 

Start numbered paragraph. 

.of 'x 'y 'z ' 


No 

Sdt odd footer to x y z. 

.oh 1 x 1 y'z 1 


No 

Sdt odd header to x y z. 

.pd 


Yes 

Print delayed text. 

■PP 

No 

Yes 

Begin paragraph. First line indented. 

.r 

Yes 

No 

Roman text follows. 

.re 


No 

Reset tabs to default values. 

■shn * 


Yes 

Section head follows; font is automatically bold, n is 
level of section, x istitle of section. 

.sk 

No 

No 

Leave the next page blank. 0 nly one page is 
remembered ahead. 

.sm x 


No 

Set x in a smaller point size 

.szift. 

lOp 

No 

Augment the point size by n points 

■tP 

No 

Yes 

Begin title page. 

.U X 


No 

Underline argument (even in troff) (nofill only). 

.uh 


Yes 

Like.sh but unnumbered. 

.xp X 


No 

Print index x. 


GroffVersion 1.09, 6 August 1992 
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groffjnm— groff mm macros 

SYNOPSIS 

groff_mgm [ options... J [files... ] 

DESCRIPTION 

The groff mm macros are intended to be compatible with theDWB mm macros with the following limitations 
N o letter macros are implemented (yet). 

No Bell Labs localisms are implemented. 

The macros ok and pm are not implemented, 
groff mm does not support cut marks 

mgm isintended to be international. Therefore it is possible to write short national macro-files that change all English text to 
the preferred language Usemgmse as an example 
groff mm has several extensions 

ic [i] Begin onecolumn processing. A i as argument disables the page break. 

app name text Begin an appendix with the name name. Automatic naming occurs if name isThe 

appendixes starts with A if auto is used. A new pageisqected, and a header is also 
produced if the number variable Aph is non-zero. This isthe default. The appendix 
always appear in the list of contents with the correct page number. The name 
appendix can be changed by setting the string App to the desired text. 
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Same as .app, but the page number isincremented with pages. This is used 
when diagrams or other non-formatted documents are included as appen¬ 
dixes. 

Begin box (as the ms macro) Draws a box around the text. 

End box. Finish the box. 

Start of broken variable-item list. Like vl but text begins always at the next 
line 

cover begins a coversheet definition. It is important that .cover appears 
before any normal text, .cover uses a r g to build thefilename/usr/iib/groff/ 
tmac/mm/arg.cov. Therefore, it is possible to create unlimited types of 
covershedts ms.cov issupposed to look like the ms coversheet. .cover requires 
a . covend at the end of the cover definition. Always use this order of the cover 
macros 

.COVER 

.TL 


.AU 


.AS 

.AE 

.COVEND 

H owever, only .tl and . au are required. 

covend This finishes the cover description and prints the cover page It isdefined in 

the cover file. 

gethn refname [var name ] Includes the header number where the corresponding setr r ef name was 

placed. Will bex.x.x. in passl. See initr. If varname isused, gethn sdtsthe 
stri ng vari able» a r n a me to the header number. 

getpn refname [varname] Indudesthe page number where the corresponding setr r ef name wasplaced. 

Will be 9999 in passl. See initr. Ifvarname isused, getpn sets the string 
variableva r na me to the page number. 

getr refname Combines gethn and getpn with the text 'chapter 1 and ', page 1 . The string 

Or f contains the text for reference: .ds Qrf See chapter \\*[Qrfh], page 
\\*[Qrf p ]. Or f may be changed to support other languages Strings Qrf h and 
Qrf p are set by getr and contain the page and header number. 

getst refname [varname] I ndudes the string saved with the second argument to .setr. Will be dummy 

string in passl. Ifvarname isused, getst sets the string variable var name to the 
saved string. See initr. 

initr filename I nitialize the reference macros. References will be written to f i i ena me. tmp 

and f i i ename .qrf. Requires two passes with groff. The first looks for 
references and thesecond includes them, initr can be used several times, but 
it isonly the first occurrence of initr that is active. See also setr, getpn, and 

GETHN. 

mc col umn-si ze [col umn-separ at i on] Begin multiple columns Return to normal with ic. 

MT [arg [addressee]] M emorandum type. Thear g ispart of a filenamein/usr/lib/groff/tmac/mm/ 

* .mt. M emorandum type 0 through 5 are supported, including string, 
addressee just setsa variable, used intheAT&T macros 

MOVE y-pos [x-pos [I i ne- 1 engt h ] ] M OVetO a position, page offset set to *- pos . If I i ne-1 engt h is not given, the 

difference between the current and new page offset is used. U se pgform 
without arguments to return to normal. 




groff_mm 


mulb cwi spacei [cw2 s p a c e 2 [cw 3 ...]] Begin a special multi-column mode. Every column's width must 

be specified. Also, the space between the columns must be 
specified. The last column does not need any space definition. 
mulb starts a diversion and mule ends the diversion and prints the 
columns. The unit for width and space isn, but mulb accepts all 
normal unit specifications such asc and i. mulb operatesin a 
separate environment. 

muln Begin the next column. This is the only way to switch columns 

mule End the multi-column modeand print the columns. 

pgform [i i nei engt h [pagei cngt h [pageof f s et [inn This macro can be used for special formatting, such as pgform 
i i nei engt h, pagei ength and/or pageof f set . letterheads Sets can beused without arguments to reset 

everything after a move. Aline break is done unless the fourth 
argument is given. This can beused to avoid the page number 
on thefirst page while setting new width and length. 

pgnh N o header is printed on the next page. U sed to get rid of the 

header in letters or other special texts. T hismacro must be used 
before any text to inhibit the page header on thefirst page 

setr r ef name [string] Remember thecurrent header and page number asr ef name . Saves 

stri ng if stri ng isdefined. string is retrieved with .getst. See 

INITR. 

tab Reset tabs to every 5 n. Usually used to reset any previous tab 

positions 

verbon [flag [poi ntsi ]]] Begin verbatim output using Courier font. Usually for printing 

programs All characters have equal width. The point size can be 
changed with thesecond argument. By specifying thefont 
argument, itispossibleto use another font instead of Courier, 
f i ag controls several special features. It containsthesum of all 
wanted features: 

Value Description 

1 D isable the escape-character (n). T his is usually 
turned on during verbose output. 

2 Add an empty line before the verbose text. 

4 Add an empty line after the verbose text. 

8 Printtheverbosetextwith numbered lines. This 

adds four digit-sized spacesin the beginning of 
each line. Finer control is available with the 
string-vari able verb™. It containsall arguments 
to the tnoff -command .™, usually i. 

16 Indent the verbose text with fivens Thisis 

controlled by thenumber-variableverbin (in 
units). 


verboff End verbatim output. 

New variables in mgm: 

App 
Aph 


A string containing the word appendix. 

Print an appendix page for every new appendix if this number 
variable is nonzero. N o output will occur if Aph iszero, but there 
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Hpsl 

Hps2 


M01 - M012 
Qrf 


Pgps 


will always be an appendix entry in the list of contents 
Number variable with the heading pre-space level. If the heading 
level is less than or equal to Hps, then two lines precede the section 
heading instead of one. D efault isfirst level only. The real amount 
of lines is controlled by the variables Hpsi and Hps2. 

This isthenumber of lines preceding .Hwhen the heading level is 
greater than Hps. Value is in units, usually o.sv. 

This isthenumber of lines preceding .Hwhen the heading level is 
less than or equal to Hps. Valueisin units, usually iv. 

String containing figure 
String containing table. 

String containing exhibit. 

String containing equation. 

String containing contents. 

The size of an empty line. Usually o.sv, but it is i v if n isset 
(.nroff), 

Strings containing January to December. 

String containing "See chapter \\*[Qrfh], page \\n[Qrfp]. 
Controls whether header and footer point size should follow the 
current setting or just change when the header and footer is 
defined. 

Value Description 

0 Point size will only change to the current setting 

when .ph, .pf, .oh, .eh, .of, or .oe isexecuted. 
i Point size will change after every .s. Thisisthe 

default. 


Sectf Flag controlling section figures A nonzero value enables this. See 

also register N. 

Sectp Flag controlling section page numbers A nonzero value enables 

this See also register N. 

.mgm Always 1. 


A file cal led locale or iang_iocaie is read after the initiation of the global variables It istherefore possibleto localize the 
macros with a company name and so on. 


Thefollowing standard macros are implemented: 
20 
AE 

AF [n a me of firm] 

AL [type It&irt - indent [1]]]] 

AS [arg [i ndent ]] 

AST [title] 

AT t i 11 el'.:.[£] 11 e 2 ...] 

AU name [initials [I oc [dept 


B [bol d-1ext [prev-font-text [...]]] 


Begin two column processing. 

Abstract end. 

Author'sfirm. 

Start autoincrement list. 

Abstract start. Indent isspecified in ens, but scaling is allowed. 
A bstract ti tl e D efault i s 1 abstract 1 . 

Author'stitle. 

[ext [room [arg [arg 

[arg]]]]]]]] Author information. 

Begin boldface N o limit on the number of arguments 
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BE 

BI[bol d-1 ext [italic-text [bold-text [...]]] 
BL [text-indent [1]] 

BR [bold-text [roman-text [bol d-text [...]]] 

BS 

DE 

DF[f or mat [fill [rindent]]] 

DL [text- i ndent [1]] 

DS [format [fill [ri ndent ]]] 

EC [title [overri de [fI ag [re? r.a -e ]]]] 

EF [arg ] 

EH [arg] 

EN 

EQ [I abel ] 

EX [title [over r i de [f I ag [refname ]]]] 

FD [arg [1]] 

FE 

FG [title [over r i de [f I ag [refname]]]] 

FS 

H level [headi ng-text [headi ng-suffi x]] 

HC [hyphenati on-ctiaracter ] 

HM [argl [arg2[... [arg7 ]]]] 

HX dI eveI rIeveI heading-text 
HY d I e * eI rI e v eI h e a d i n g■t e x t 
HZ d I e v eI rI e v eI h e a d i n g-1 e x t 
I [i tali c- text . 

IB [i tal i c -1 ext 

IR [i tal i c -1 ext 

LB text-i ndentmark-i ndent 

LC [list I evel ] 

LE 

LI [mark [1]] 

ML mar k [t ext ■ i ndent ] 

MT [arg [addressee]] 


End bottom block. 

Bold italic. N o limit on the number of arguments. 

Start bullet list. 

Bold roman. N o limit on the number of arguments. 

Bottom block start. 

Display end. 

Begin floating display (no nesting allowed). 

D ash list start. 

Static display start. Can now have unlimited nesting. Also, right- 
adjusted text and block may be used (r or rb as format). 

Equation title. If ref name is used, then theequation number is 
saved with .setr andean be retrieved with .getst ref name. 

Even page footer. 

Even page header. 

Equation end. 

Equation start. 

Exhibit title. If r ef name isused, then the exhibit number issaved 
with .setr and can be retrieved with .getst ref name. 

Footnote default format. 

Footnote end. 

Figure title. If refname isused, then thefigure number issaved 
with .setr and can be retrieved with .getst ref name. 

Footnote start. Footnotesin displays is now possible. 

N umbered heading. 

Set hyphenation character. 

FI eading mark style. 

Unnumbered header. 

User-defined heading exit. Called just before printing the header. 
User-defined heading exit. Called just before printing the header. 
User-defined heading exit. Called just after printing the header. 

[prev-font-text 

[italic-text [...]]] Italic. 


[bol d-teiif. 

[italic-text [...]]] Italic bold. 

[r Oman-1 ext 

[italic-text [...]]] Italic roman. 

pad t y p e [ ma r k 

[Li • space [LB-space]n List begin macro. 
List status clear. 

List end. 

List item. 

M arked list start. 

M emorandum type. See above note about mt. 
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ND new- dat e 
OF [arg] 

OH [arg ] 

OP 

P [type ] 

PE 

PF [arg] 

PH [arg] 

PS 

PX 


RB [roman-text [bol d-1 ext 
RD [prompt [diversion [string]]] 


RI 


RL 

RP [arg 
RS [St ri 
S [size 


■indent [1]] 
[arg]] 
ng- name ] 
[spaci ng]] 


SP [I i nes ] 

TB [title [over r i d e [f I ag [ref name ] ]]] 


TC [si evei 


[spaci ng 


TE 

TH [N] 
TL 


TM [numl [num2 [...]]] 


N ew date 
Odd page footer. 

0 dd page header. 

Skip to odd page. 

Begin new paragraph. 

Picture end. 

Page footer. 

Page header. 

Picture start (from pic). 

Page header user-defined exit. 

Roman. 

[roman-text [...]]] Roman-bold. 

Readtodiversion and/orstring. 
Reference end. 


[roman-text [...]]] Roman italic. 

Reference list start. 

Produce reference page. 

Reference start. 

Set point size and vertical spacing. If any argument equals p, then the 
previous value is used. A c meanscurrent value, and d meansdefault 
value. If + or - isused before the value, an increment or decrement of 
the current value is done. 

Sdt adjustment. 

Skip pages. 

Make a string smaller. 

Space vertically, lines can have any scaling factor, such as 3i or 8v. 

T able title. If ref name is used, then thetable number issaved with 
•setr and can be retrieved with .getst ref name. 

[tlevel [tab [hi [h2 
[h3 [h4 [h5 ]]]]]]]] ] 

Table of contents. All texts can be redefined, new string variables 

Lifg, Litb, Liex, Liec, and Licon Contain "Figure", "TABLE", "Exhibit", 
■Equation", and "contents". These can be redefined to other 
languages 
Table end. 

T able header. 

Begin title of memorandum. 

Technical memorandum numbers used in .mt. Unlimited number of 
arguments may be given. 

Top of page user-defined macro. N ote that header and footer is 
printed in a separate environment. Line length ispreserved. 

Table start. 

U ser-defined table of contents exit. 

User-defined table of contents exit (no "contents"). 




groff_mm 


VL [Uxt■ indent [mark-i ndent [1]]] 
VM [t op [bottom]] 

WC [f or mat ] 

Strings used in mgm: 

EM 


HP 

Lf 


Rp 

Tm 


N umber variables used in mgm: 

Cl=2 

Cp=0 


De=0 

Df=5 

Ds=1 

E]=0 

Eq=0 

Fs=1 


Variable-item list start. 

Vertical margin. 

Footnote and display width control. 

Em dash string. 

Font list for headings, usually "222222 2 ". Nonnumeric font 
names may also be used. 

Point size list for headings. Usually "0 00000 0 11 , which isthe 
sameas n i 0 10 10 10 10 10 10 - . 

Contains "list of figures - . 

Contains "list of tables". 

Contains "list of exhibits - . 

Contains "list of equations". 

Contains "REFERENCES". 

C ontains \ (tm, trademark. 


Contents level [0:7]; contents saved if heading level <=ci. 

Eject page between list of xxxx if cp == 0 . 

D ebug flag, values greater than 0 produce varying degree of debug. A 
value of 1 gives information about the progress of formatting. 

Eject after floating display isoutput [0:1]. 

Floating keep output [0:5]. 

Space before and after display if =1 [0:1]. 

Eject page. 

Equation label adjust 0 =left, i=right. 

Footnote spacing. 

FI eading counters. 

FI eading break level [0:7], 

FI eading centering level [0:7], 

H eading temporary indent [0:2]. oisno indent, left margin. 1 is 
indent to right, like .p 1.2 is indent to lineup with text part of 
preceding heading. 

FI eading space level [0:7] 

FI eading numbering type 0 is multiple ( 1 . 1 . 1 ...). 1 issingle. 

U nnumbered heading level. 

H yphenation in body. 0 is no hyphenation. 1 is hyphenation Mon. 

E nables ( 1 ) or disables ( 0 ) the printing of a list of figures, list of tables, 
list of exhibits, and list of equations. 

List indent, used by .al. 

List space if current list level isgreaterthan ls, then no spacing 
occurs around lists 
Numbering style [0:5]: 

0 = (D efault) N ormal header for all pages. 

1 = Header replaces footer on first page; header is empty. 

2 = Page header is removed on thefirst page. 
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3 =Section page numbering enabled. 

4 = Page header is removed on thefirst page. 

5 = Section page and section figure numbering enabled. See also the 
number register sectf and sectp. 

Np=0 N umbered paragraphs. 0 is not numbered. 1 is numbered in first-level 

headings. 

of=0 Format of figure, table, exhibit, and equation titles 0 is - . ". 1 is ■ - ■. 

p Current page number, usually the same as % unless section-page 

numbering is enabled. 

pi=5 Paragraph indent. 

ps=i Paragraph spacing. 

pt=0 Paragraph type 0 is left-justified. 1 is indented .p. 2 is indented .p 

except after .h, .de, or .le. 

si=5 Display indent. 

AUTHOR 

Jorgen Hagg, Lund Institute of Technology, Sweden (jh@efd.ith.se). 

FILES 

/usr/lib/groff/tmac/tmac.gm 

/usr/lib/groff/tmac/mm/*.cov 

/usr/lib/groff/tmac/mm/*.MT 

/usr/Hb/groff/tmac/mm/locale 


SEE ALSO 

groff(l), gtroff(l), gtbl(l), gpic(l), geqn(l), mm(7), mgmse(7) 


GroffVersion 1.09,14 February 1994 


groffjis 

groff_ms— groff ms macros 

SYNOPSIS 

groffjngs [ options... ] [files... ] 

DESCRIPTION 

This manual page describes the GN U version ofthems macros, which is part of the groff document formatting system. The 
groff ms macros are intended to be compatible with thedocumented behavior of the 4.3 BSD U N IX ms macros subject to 
thefollowing limitations: 

The internals of groff ms are not similar to the i nternals of U NIX ms, so documents that depend upon i implementation 
detaiIs of U NIX ms might not work with groff ms. 

T here is no support for typewriter-like devices. 

Berkeley localisms in particular the tm and ct macros are not implemented, 
groff ms does not provide cut marks 

M ultiple line spacing is not allowed. (U se a larger vertical spacing instead.) 
groff ms doesnotwork in compatibility mode (such as with the -c option). 





groff_ms 


The error-handling policy of graft ms isto detect and report errors, rather than silently ignore them. 

The graft ms macros use many features of G N U troff and therefore cannot be used with any other traff. 

Bell Labs localisms are not implemented in either theBSD ms macros or in the graft ms macros 

SomeU NIX ms documentation says that the cw and gw number registers can be used to control the column width and gutter 

width. This is not the case. Thesenumber registers are not used in graft ms. 

M acrosthat cause a reset set the indent. M acrosthat change the indent do not increment or decrement the indent, but rather 
set it absolutely. This can cause problems for documents that define additional macros of their own. The solution isto not 
use the in request but instead to use the rs and re macros 

T he number register gs is set to i bythegraff ms macros but is not used by the UN IX ms macros It is intended that 
documents that need to determine whether they are being formatted with UN IX ms orgnoff ms use this number register. 
Footnotes are implemented so that they can safely be used within keeps and displays. Automatically numbered footnotes 
within floating keeps are not recommended. It is safe to have another \** between a \** and the corresponding . fs; it is 
required only that each .fs occur after the corresponding\** and that the occurrences of .fs are in the same order asthe 
corresponding occurrences of v**. 

Thestrings\*{ and \*} can be used to begin and end a superscript. 

SomeU NIX V10 ms features are implemented. TheB, i, and bi macroscan have an optional third argument that is printed 
in the current font before thefirst argument. There is a macro cw like b that changes to a constant-width font. 

Thefollowing strings can be redefined to adapt thegroff ms macros to languages other than English: 

String DefaultValue 

REFERENCES References 

ABSTRACT ABSTRACT 

TOC Table of Contents 

M0NTH1 January 

M0NTH2 February 


M0NTH3 

M0NTH4 

M0NTH5 

M0NTH6 

M0NTH7 

M0NTH8 

M0NTH9 

M0NTH11 
M0NTH12 



May 

June 

July 


August 

September 

October 

December 


The font family is reset from the string fam; at initialization if this string is undefined, it is set to the current font family. The 
point size vertical spacing, and inter-paragraph spacing for footnotes are taken from the number registers fps, fvs, and fpd; 
at initialization, these are set to \n<ps-2, \n[FPS]+2, and \n(PD/2; however, if any of these registers was defined before 
initialization, it is not set. The hyphenation flagsfasset by the .hy request) are set from the hy register; if this was not defined 
at initialization, it isset to i4. 

Right-aligned displays are available with .ds Rand .rd. 

Thefollowing conventions are used for names of macros,strings, and number registers External names available to 
documents that use thegroff ms macroscontain only uppercase letters and digits. Internally, the macros are divided into 
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modules. N amesused only within one module are of the form mod ui e*name. Names used outside the module in which they 
are defined are of the form modui e@name. Names associated with a particular environment are of theformenv ronment: n a me; 
these are used only within the par module, and name does not have a module prefix. Constructed names used to implement 
arrays are of the form array ii nde*. Thus, thegroff ms macros reserve the following names: 

Names containing* 

Names containing!? 

Names containing: 

N ames containing only uppercase letters and digits 


FILES 

/usr/lib/groff/tmac/tmac.gs 

SEE ALSO 

groff(l), gtroff(l), gtbl(l), gpic(l), geqn(l), ms(7) 


Groff Verson 1.09, 9 January 1994 


hier 

hier— Description of the filesystem hierarchy. 


DESCRIPTION 

A typical Linux system has, among others, thefollowing directories: 

/ This is the root directory. T hisis where the whole tree starts 

/bin Thisdirectory contains executable programs that are needed in single-user mode and to 

bring the system up or repair it. 

/boot Containsstatic filesfor the boot loader. Thisdirectory only holds the files that are 

needed during the boot process. The map installer and configuration files should go to / 
sbin and /etc. 

/dev Special or device files that refer to physical devices. See mknod(l). 

/ dos If both M S-DOS and Linux are run on one computer, this is a typical place to mounta 

DOS filesystem. 

/etc C ontains configuration files that are local to the machi ne. Some larger software 

packages, such asXll, can have their own subdirectories below /etc. Site-wide 
configuration files may be placed here or in /usr/etc. N evertheless, programs should 
always look for these files in /etc and you may have links for these files to /usr/etc. 

/etc/skei When anew user account is created, filesfrom thisdirectory are usually copied into the 

user's home directory. 

/etc/xii Configuration filesfor the X11 window system. 

/home On machines with home directoriesfor users, these are usually beneath thisdirectory, 

directly or not. The structure of thisdirectory depends on local administration 
decisions 

/ lib Thisdirectory should hold those shared libraries that are necessary to boot the system 

and to run the commands in the root filesystem. 

/mnt This is a mount point for temporarily mounted filesystems. 

/proc This is a mount point for the proc filesystem, which provides information about 

running processes and the kernel. This pseudo-filesystem isdescri bed in more detail in 
proc(5). 



/UST/X11R6 

/usr/X11R6/bin 

/usr/X11R6/lib 

/usr/X11R6/lib/X11 

/usr/X11R6/include/X11 

/usr/bin 


/usr/bin/X11 

/usr/dict 

/usr/etc 


/usr/include/X11 

/usr/include/asm 

/usr/include/linux 


/usr/include/g++ 

/usr/lib 

/usr/lib/X11 

/usr/lib/gcc-lib 

/usr/lib/groff 

/usr/lib/uucp 

/usr/lib/zoneinfo 

/usr/local 

/usr/local/bin 

/usr/local/doc 

/usr/local/etc 

/usr/local/lib 

/usr/local/info 

/usr/local/man 

/usr/local/sbin 


Like /bin, this directory holds commands needed to boot the system but usually not 
executed by normal users 

This directory contains temporary files that may be deleted with no notice such asbya 
regular job or at system bootup. 

This directory is usually mounted from a separate partition. It should hold only 
sharable, read-only data so that it can be mounted by various machines running Linux. 
TheX window system, version 11, release 6. 

Binaries that belong to theX window system; often, there isa symbolic link from the 
more traditional /usr/bin/xii to here 
D ata files associated with theX window system. 

These contain miscellaneous files needed to run X; Often, there is a symbolic linkfrom 
/usr/iib/xii to this directory. 

Contains include files needed for compiling programs using theX 11 window system. 
Often, there is a symbolic linkfrom /usr/inciude/xii to this directory. 

This is the primary directory for executable programs. M ost programs executed by 
normal users that are not needed for booting or for repairing the system and that are not 
installed locally should be placed in this directory. 

This is the traditional place to look for Xll executables; on Linux, it usually isa 
symbolic link to /usr/xiiR6/bin. 

This directory holds files containing word lists for spell-checkers. 

Site-wide configuration files to be shared between several machines may be stored in this 
directory. However, commands should always reference those files using the /etc 
directory. Links from files in /etc should point to the appropriate files in /usr/etc. 
IncludefilesfortheC compiler. 

Includefilesfor theC compiler and theX window system. This is usually a symbolic 

link to /usr/X11R6/include/X11. 

Include files that declare some assembler functions This should be a symbolic link to/ 

usr/src/linux/include/asm. 

This contains information that may change from system release to system release and 
should be a symbolic link to /usr/src/iinux/inciude/iinux to gdt at operating-system- 
specific information. 

Include files to use with theGNU C-H-compiler. 

0 bject libraries, including dynamic libraries, plus some executables that usually are not 
invoked directly. M ore complicated programs may havewhole subdirectories there. 

The usual place for data files associated with X programs and configuration files for the 
X system itself. On Linux, it usually isasymbolic link to /usr/xi iR6/iib/xii. 
Containsexecutables and includefilesfor theGNU C compiler, gcc(l). 

Files for theGNU groff document formatting system. 

Files for uucp(l). 

Files for time zone information. 

This is where programsthat are local to thesite typically go. 

Binaries for programslocal to thesite go there. 

Local documentation. 

Configuration files associated with locally installed programs go there. 

Files associated with locally installed programs go there. 

Info pages associated with locally installed programsgo there. 

M an pages associated with locally installed programs go there 
Locally installed programs for system administration. 
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/usr/local/src 

/usr/man 

/usr/man/cat[1-9] 
/usr/man/l o ca I e /man[1 -9] 
/usr/sbin 


/usr/src/linux 

/usr/tmp 


/var/adm 

/var/lock 


/var/log 

/var/preserve 

/var/run 

/var/spool 

/var/spool/at 

/var/spool/cron 

/var/spool/lpd 

/var/spool/mail 

/var/spool/smail 

/var/spool/news 

/var/spool/uucp 

/var/tmp 


Source code for locally installed software. 

M an pages go in there into their subdirectories 

These directories contain preformatted manual pages according to their man page 
section. 

These directories contain manual pages that are in source code form. Systems that use a 
unique language and code set for all manual pages may omit the i ocai e substring. 

This directory contains program binaries for system administration that are not essential 
for the boot process, for mounting /usr, or for system repair. 

Source files for different parts of the system. 

This contains the sourcesfor the kernel of the operating system itself. 

An alternative place to store temporary files; This should be a link to /var/tmp. 

This directory contains files that may change in size, such as spool and log files. 

This directory is superseded by/var/iog and should beasymbolic link to /var/iog. 

Lock files are placed in thisdirectory. T he naming convention for device lock files is 
lck. .devi ce wheredevi ce isthedevice'snamein thefilesystem. Theformat used isthat 
ofHDU UUCP lock files— that is^ lock files contain a PI D asa 10-byte ASCI I decimal 
number, followed by a newline character. 

M iscdlaneous log files. 

This is where vi(l) saves edit sessionsso they can be restored later. 

Runtime variablefiles, such as files holding process identifiers (PI Ds) and logged user 
information (utmp). Files in thisdirectory are usually cleared when the system boots 
Spooled (or queued) files for various programs. 

Spooled jobsforat(l). 

Spooled jobsforcron(l). 

Spooled filesfor printing. 

U sens' mailboxes 

Spooled files for the smaii(l) mail delivery program. 

Spool directory for the news subsystem. 

Spooled filesfor uucp(l). 

Like / tmp, thisdirectory holds temporary files stored for an unspecified duration. 


C0NF0RMST0 

TheLinuxfilesystem standard, releasel.2. 

BUGS 

This list is not exhaustive; different systems may be configured differently. 

SEE ALSO 

find(l), in(l), mount(l), proc(5), T he Linux Filesystem Standard 

Linux, 10 February 1996 


hostname 

hostname- H ostname resolution description. 
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DESCRIPTION 

Hostnames are domains. A domain isa hierarchical, dot-separated list of subdomains For example, the machinemonet in the 
Berkeley subdomain of theEDu subdomain of the Internet Domain N ameSystem isrepresented asmonet.Berkeiey.EDu (with 
no trailing dot). 

H ostnames are often used with network client and server programs which must generally translate the name to an address 
for use. (This task is usually performed by the library routine gethostbyname(3).) The default method for resolving hostnames 
by thelnternet name resolver is to followRFC 1535's security recommendations Actions can betaken by the administrator 
to override these recommendations and to have the resolver behave the same as earlier, non-RFC 1535 resolvers 
Thedefault method (using RFC 1535 guidelines) follows. 

If the name consists of a single component (that is contains no dot) and if the environment variable hostaliases issdtto the 
nameof a file, that file issearched for a string matching the input hostname Thefile should consist of lines madeup of two 
strings separated by whitespace the first of which is the hostname alias and the second of which is the complete hostname to 
be substituted for that alias If a case-insensitive match is found between the hostname to be resolved and the first field of a 
line in thefile, the substituted name is looked up with no further processing. 

If there is at least one dot in the name then the name isfirst tried as is T he number of dots to cause this action is 
configurable by setting the threshold using the ndots option in /etc/resoiv.conf (default is i). If the name ends with a dot, 
the trailing dot is removed, and the remaining name is looked up (regard I ess of the setting of the ndots option) and no 
further processing isdone 

If the input name does not end with a trailing dot, it is looked up by searching through a list of domains until a match is 
found. If neither the search option in the /etc/resoiv.conf file or the localdomain environment variable is used, then the 
search list of domainscontainsonly the full domain specified bythedomain option (in /etc/resoiv.conf) orthedomain 
used in the local hostname (see hostname(l) and resoiver(5)). For example, if the domain option issetto cs.Berkeiey.EDu, 
then onlycs.Berkeiey.EDu is in the search list and is the only domain appended to the partial hostname For example, a 
setting of lithium rnakesiithium.cs.Berkeiey.EDu the only name to be tried using the search list. 

If the search option isused in /etc/resoiv.conf or the environment variable, localdomain issdt by the user, then the search 
list includes what is set by these methods. For example if the search option contained cs.Berkeiey.EDu cchem.Berkeiey.EDu 
Berkeiey.EDu, then the partial hostname (such as lithium) is tried with each domain name appended (in the same order 
specified). The resulting hostnames that are tried include 

lithium.CS.Berkeley.EDU 
lithium.CChem.Berkeley.EDU 
lithium.Berkeley.EDU 

The environment variable localdomain overrides the search and domain options, and if both search and domain options are 
present in the resolver configuration file then only the last one listed is used (see resoiver(5)). 

If the name was not previously tried "as is" (that is, it fell below the ndots threshold or did not contain a dot), then the name 
as originally provided is attempted. 


SEE ALSO 

gethostbyname(3), resolver(5), mailaddr(7), named(8) 
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iso_8859_1 

iso_8859_i-ThelSO 8859-1 character set encoded in octal, decimal, and hexadecimal. 

DESCRIPTION 

ThelSO 8859 standard includes several 8-bit extensions to the ASCI I character set (also known as I SO 646-1RV). Especially 
important is I SO 8859-1, the Latin Alphabet N o. 1, which has become widely implemented and may already be seen as the 
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de facto standard ASCII replacement. ISO 8859-1 supportsthefollowing languages; Afrikaans, Basque, Catalan, Danish, 
Dutch, English, Faeroes, Finnish, French, Galician,German, Icelandic, Irish, Italian, Norwegian, Portuguese, Scottish, 
Spanish,and Swedish. Note that the ISO 8859-1 characters are also thefirst 256 charactersof ISO 10646 (Unicode). 

ISO 8859 ALPHABETS 





The full set of 1 SO 8859 alphabets includes 



ISO 8859-1 




West European languages (Latin-1) 

ISO 8859-2 




East European languages (Latin-2) 

ISO 8859-3 




Southeast European and miscellaneous languages (Latin-3) 

ISO 8859-4 




Scandinavian/Baltic languages (Latin-4) 

ISO 8859-5 




Latin/Cyrillic 

ISO 8859-6 




Latin/Arabic 

ISO 8859-7 




Latin/Greek 

ISO 8859-8 




Latin/FI ebrew 

ISO 8859-9 




Latin-1 modification for Turkish (Latin-5) 

ISO 8859-10 




Lappish/N ordic/Eskimo languages (Latin-6) 

ISO 8859-1 CHARACTERS 




The followi ng table displays the characters i 

n ISO 8859 Latii 

>1, which are printable and unlisted in theascii(7) manual 

page. 





Oct 

Dec 


Hex 

Char Description 

240 

160 


A0 

N o-break space 

241 

161 


A1 

i Inverted exclamation mark 

242 

162 


A2 

<t Cent sign 

243 

163 


A3 

£ Pound sign 

244 

164 


A4 

$ C urrency sign 

245 

165 


A5 

¥ Yen sign 

246 

166 


A6 

| Broken bar 

247 

167 


A7 

§ Section sign 

250 

168 


A8 

Diaeresis 

251 

169 


A9 

© Copyright sign 

252 

170 


AA 

- Feminineordinal indicator 

253 

171 


AB 

« Left-pointing double angle quotation 

mark 

254 

172 


AC 

-> N ot sign 

255 

173 


AD 

Soft hyphen 

256 

174 


AE 

® Registered sign 

257 

175 


AF 

M acron 

260 

176 


B0 

° D egree sign 

261 

177 


B1 

± Plus-minussign 

262 

178 


B2 

2 Superscript two 

263 

179 


B3 

3 Superscript three 
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Oct Dec 

"264 180~ 

265 181 

266 182 

267 183 

270 184 

271 185 

272 186 

273 187 

274 188 

275 189 

276 190 

277 191 

300 192 

301 193 

302 194 

303 195 

304 196 

305 197 

306 198 

307 199 

310 200 

311 201 

312 202 

313 203 

314 204 

315 205 

316 206 

317 207 

320 208 

321 209 

322 210 

323 211 

324 212 

325 213 

326 214 

327 215 

330 216 

331 217 

332 218 

333 219 


B5 

B6 

B7 

B8 

B9 

BA 

BB 


BC 
BD 
BE 
BF 
CO 
Cl 
C2 
C3 
C4 
C5 
C6 
C7 
C8 
C9 
CA 
CB 
CC 
CD 
CE 
CF 
DO 
D 1 
D 2 
D3 
D4 
D5 
D6 
D7 
D8 
D9 
DA 
DB 


Char Description 

Acute accent 
M icro sign 
'|[ Pilcrow sign 

Middle dot 

g Cedilla 

1 Superscript one 

2 M asculine ordinal indicator 

» Right-pointing double angle 

quotation mark 

1/4 V ulgar fraction one quarter 

1/2 V ulgar fraction one half 

3/4 V ulgar fraction three quarters 

i Inverted question mark 

A Latin capital letter A with grave 

A Lati n capital letter A with acute 

A Latin capital letter A with circumflex 

A Latin capital letter A with tilde 

A Latin capital letter A with diaeresis 

A Latin capital letter A with ring above 

/E Latin capital ligature AE 

C Latin capital letter C with cedilla 

E Latin capital letter E with grave 

E Latin capital letter E with acute 

E Latin capital letter E with circumflex 

E Latin capital letter E with diaeresis 

i Latin capital letter I with grave 

i Latin capital letter I with acute 

i Latin capital letter I with circumflex 

I Latin capital letter I with diaeresis 

D Latin capital letter eth 

N Latin capital letter N with tilde 

0 Latin capital letter 0 with grave 

6 Latin capital letter 0 with acute 

0 Latin capital letter 0 with circumflex 

0 Latin capital letter 0 with tilde 

0 Latin capital letter 0 with diaeresis 

x M ultiplication sign 

0 Latin capital letter 0 with stroke 

0 Latin capital letter U with grave 

U Latin capital letter U with acute 

U Latin capital letter U with circumflex 


continues 
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Oct 

Dec 

Hex 

Char 

D escription 

334 

220 

DC 

0 

Latin capital letter U with diaeresis 

335 

221 

DD 

Y 

Latin capital letter Y with acute 

336 

222 

DE 


Latin capital letter thorn 

337 

223 

DF 

13 

Latin small letter sharps 

340 

224 

E0 

a 

Latin small letter a with grave 

341 

225 

El 

a 

Latin small letter a with acute 

342 

226 

E2 

a 

Latin small letter a with circumflex 

343 

227 

E3 

a 

Latin small letter a with tilde 

344 

228 

E4 

a 

Latin small letter a with diaeresis 

345 

229 

E5 

a 

Latin small letter a with ring above 

346 

230 

E6 

ae 

Latin small ligature ae 

347 

231 

E7 

? 

Latin small letter c with cedilla 

350 

232 

E8 

e 

Latin small letter ewith grave 

351 

233 

E9 

e 

Latin small Idtter ewith acute 

352 

234 

EA 

e 

Latin small letter ewith circumflex 

353 

235 

EB 

e 

Latin small letter ewith diaeresis 

354 

236 

EC 

i 

Latin small letter i with grave 

355 

237 

ED 

[ 

Latin small letter i with acute 

356 

238 

EE 

\ 

Latin small Idtter i with circumflex 

357 

239 

EF 

f 

Latin small letter i with diaeresis 

360 

240 

FO 

a 

Latin small letter eth 

361 

241 

FI 

n 

Latin small letter n with tilde 

362 

242 

F2 

6 

Latin small letter o with grave 

363 

243 

F3 

6 

Latin small letter o with acute 

364 

244 

F4 

6 

Latin small letter o with circumflex 

365 

245 

F5 

6 

Latin small letter o with tilde 

366 

246 

F6 

6 

Latin small letter o with diaeresis 

367 

247 

F7 

-r 

Division sign 

370 

248 

F8 

0 

Latin small letter o with stroke 

371 

249 

F9 

u 

Latin small letter u with grave 

372 

250 

FA 

u 

Latin small letter u with acute 

373 

251 

FB 

1 

Latin small letter u with circumflex 

374 

252 

FC 

u 

Latin small letter u with diaeresis 

375 

253 

FD 

y 

Latin small letter y with acute 

376 

254 

FE 


Latin small letter thorn 

377 

255 

FF 

y 

Latin small letter y with diaeresis 


SEE ALSO 

ascii(7) 


11 July 1995 
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locale 

Locale— Description of multi-language support. 

SYNOPSIS 

#include <locale.h> 

DESCRIPTION 

A locale is a set of language and cultural rules These cover aspects such aslanguagefor messages, different character sets, 
lexigraphic conventions and so on. A program needs to beableto determine its locale and act accordingly to be portable to 
different cultures 

The header <iocaie.h> declares data types functionsand macros that are useful in this task. 

Thefunctions it declares are setiocaieo to set the current locale and locaieconvo to get information about number 
formatting. 

There are different categories for local information a program might need; they are declared as macros. Using them as the 
first argument to the setiocaieo function, it is possible to set one of these to the desired locale: 
lc_collate T his is used to change the behavior of thefunctions strcoii() and strxfrmo, which 

are used to compare strings in the local alphabet. For example the German sharp sis 
sorted as "ss." 

lc_type Thischangesthebehaviorofthecharacter handling and classification functions, 

such asisuppero and touppero and the multi-byte character functions such as 
mblen() Or wctombf). 

lc_monetary C hangesthe behavior of the information returned by locaieconvo, which describes 

the way numbers are usually printed, with details such as decimal point versus 
decimal comma. 

lc_messages C hanges the language messages are displayed in. 

lc_time Changes the behavior of thestrftimeo function to display the current time in a 

locally acceptable form; for example, most of Europe uses a 24-hour clock versus the 
U.S. 12-hour clock. 

lc_all All of the above. 

If the second argument to setiocaieo isempty string for thedefault locale it isdetermined using the following steps: 

1. If there is a non-null environment variable lc_all, the valueof lc_all isused. 

2. If an environment variable with the same name as one of the preceding categories exists and is non-null, its value is used 
for that category. 

3. If there is a non-null environmentvariableLANG.thevalueof lang isused. 

Values about local numeric formatting are made available in astruct iconv returned by the locaieconvo function, which has 
thefollowing declaration: 
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/* First three chars are a currency symbol from ISO 4217. 

Fourth char is the separator. Fifth char is 1 '. */ 
char *int_curr_symbol; 

char *currency_symbol; /* Local currency symbol. */ 
char *mon_decimal_point; /* Decimal point character. */ 
char *mon_thousands_sep; /* Thousands separator. */ 
char *mon_grouping; /* Like 'grouping' element (above). */ 
char *positive_sign; /* Sign for positive values. */ 
char *negative_sign; /* Sign for negative values. */ 
char int_frac_digits; /* Int'l fractional digits. */ 
char frac_digits; /* Local fractional digits. */ 

/* 1 if currency_symbol precedes a positive value, 8 if succeeds. */ 
char_p_cs_precedes; 

/* 1 if a space separates currency_symbol from a positive value. */ 
char_p_sep_by_space; 

/* 1 if currency_symbol precedes a negative value, 8 if succeeds. */ 
char_n_cs_precedes; 

/* 1 if a space separates currency_symbol from a negative value. */ 
char_n_sep_by_space; 

/* Positive and negative sign positions: 

8 Parentheses surround the quantity and currency_symbol. 

1 The sign string precedes the quantity and currency_symbol. 

2 The sign string succeeds the quantity and currency_symbol. 

3 The sign string immediately precedes the currency_symbol. 

4 The sign string immediately succeeds the currency_symbol. */ 
char_p_sign_posn; 

char_n_sign_posn; 


C0NF0RMST0 

POSIX.1 

At the moment, the only locales supported by Linux are the portable c, posix (identical to the C locale), iso-8859-i 
(European Latin-1), and koi-8 (Russian) locales 

SEE ALSO 

setlocale(3), localeconf(3), locale(l), localedef(l) 

Linux, 24 April 1993 


mailaddr 

maiiaddi — M ail addressing description. 

DESCRIPTION 

M ail addresses are based on theARPAN ET protocol listed at the end of thismanual page. These addresses are in the general 
format 


A domai n is a hierarchical dot separated list of subdomains For example the address 

eric@monet.be rkeley.edu 

is usually interpreted from right to left. The message should go to the AR PA name tables (which do not correspond exactly 
to the physical ARPAN ET) and then to the Berkeley gateway, after which it should go to the local host monet. When the 
message reaches monet, it isdelivered to the user eric. 
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Unlike someother forms of addressing, this does not imply any routing. Thus, although this address is specified as an ARPA 
address, it might travel by an alternate route if that were more convenient or efficient. For example, at Berkeley, the 
associated message would probably go directly to monet over the Ethernet rather than go via the Berkeley AR PAN ET 
gateway. 

ABBREVIATION 

U nder certain circumstances, it might not be necessary to type the entire domain name I n general, anything following the 
first dot may be omitted if it isthe same as the domain from which you are sending the message For example a user on 
caider.berkeiey.edu could send to eric&nonet without adding theberkeiey.edu because it isthe sameon both sending and 
receiving hosts 

Certain other abbreviations may be permitted as special cases. For example at Berkeley, ARPAN ET hosts may dereferenced 
without addingtheberkeiey.edu as long as their names do not conflict with a local host name. 

COMPATIBILITY 

Certain old address formats are converted to thena/v format to provide compatibility with the pre/ious mail system. In 
particular, 


is allowed and 


is converted to 


to be consistent with the rcp(l) command. 
Also, the syntax 


is converted to 

user@host .UUCP 

This is usually converted back to the host tuser form before being sent on for compatibility with older UUCP hosts 
The current implementation isnotableto route messages automatically through theUUCP network. Until that time you 
must explicitly tell the mail system which hosts to send your message through to get to your final destination. 

CASE DISTINCTIONS 

Domain names (anything after the e sign) may be given in any mixture of uppercase and lowercase with the exception of 
UUCP hostnames M ost hostsaccept any combination of case in usernames with the notable exception ofMULucs sites 

ROUTE-ADDRS 

U nder some circumstances it might be necessary to route a message through several hosts to get it to thefinal destination. 
Usually, this routing is done automatically, but sometimes it is desirable to route the message manually. Addresses that show 
these relays are termed "route-addrs." T hese use the syntax 


This specifies that the message should be sent to host a, from there to host b, and finally to hostc. This path isforced even if 
there isa more efficient path tohostc. 

Route-addrs occur frequently on return addresses because these are generally augmented by the software at each host. Itis 
generally possible to ignore all buttheuser ©domai n part of the address to determinetheactual sender. 
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POSTMASTER 

Every site is required to havea user or user alias designated "postmaster" to which problems with the mail system may be 
addressed. 

OTHER NETWORKS 

Some other networks can be reached by giving the name of the network as the last component of the domai n. T his is not a 
standard feature and might not be supported at all sites. For example messages to CSN ET or BITN ET sites can often be 

sent to u s e r @h o s t .CSNET Or user @host .BITNET. 

BUGS 

T he R FC 822 group syntax (g r o u p: u s e r 1 , u s e r 2 , u s e r 3 ;) is not supported except in the special case of group :; because of a 
conflict with old berknet-style addresses 
RouteAddress syntax is grotty. 

UUCP- and ARPAN ET-style addresses do not coexist politely. 

SEE ALSO 

maii(l), sendmaii(8); Crocker, D. FI., Standard for the Format of Arpa Internet Text M essages, RFC 822. 

14 February 1989 


man 

man— M acrosto format man pages 

SYNOPSIS 

groff -Tascii -man file ... 
groff -Tps -man file ... 

DESCRIPTION 

This manual page explains thegroff tmac.an macro package This macro package should be used by developers when writing 
or porting man pages for Linux. It isfairly compatiblewith other versionsof this macro package so porting man pages 
should not be a major problem (exceptions include the N ET-2 BSD release, which usesa totally different macro package). 

N otethat N ET-2 BSD man pages can be used with groff simply by specifying the -mdoc option instead of the -man option. 
Using the -mandoc option is however, recommended because this automatically detects which macro package isin use 

PREAMBLE 

Thefirst command in a man page should be 

.TH title section date source manual , 


title The title of the man page (such as man). 

secti on Thesection number the man page should be placed in (such as7). 

date The date of the last revision; remember to change this every timea change is made 

to the man page because this isthe most general way of doing version control, 
source Thesourceof thecommand. 

For binaries, use something such asGN U, N ET-2, SLS Distribution, M CC 
Distribution. 

For system calls, use the version of the kernel that you are currently looking at: 
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Linux 0.99.11. 

For library calls, use the source of the function: GN U, BSD 4.3, Linux DLL 4.4.1. 
The title of the manual (such asLinux Programmer'sM anual). 


The manual sections are traditionally defined as follows: 


1 Commands 

2 System calls 

3 Library calls 

4 Special files 

5 Fileformatsand conventions 

6 Games 

7 M aero packages and conventions 

8 System management commands 

9 Kernel routines 


T hose commands that can be executed by the user from within a shell. 

Those functions that must be performed by the kernel. 

M ost of the libc functions, such assort(3). 

Files found in / dev. 

Theformatfor /etc/passwd and other human-readable files. 

A description of the standard filesystem layout, this man page, and other things. 
Commands such asmount(8), which only root can execute. 

Thisisa non-standard manual section and isincluded because the source code to 
the Linux kernel isfreely available under the GNU Public License and many 
people are working on changes to the kernel. 


FONTS 

Although there are many arbitrary conventions for man pages in the UN IX world, the existence of several hundred Linux- 
specific man pages defines the standards: 

For functions, the arguments are always specified using italics, even in thesYNOPSis section, where the rest of the function is 
specified in bold: 

int myfunction(int argc, char **arg»); 

Filenames are always in italics (such as/usr/inciude/stdio.h), except in thesYNOPSis section, where included files arein bold 
(SUCh as#include <stdio.h>). 

Special macros, which are usually in uppercase, are in bold (such asMAxiNT). 

W hen enumerating a list of error codes, the codes are in bold (this list usually uses the .tp macro). 

Any reference to another man page(orto thesubject of the current man page) is in bold. If the manual section number is 
given, it is given in roman, without any spaces (such asman(7)). 

The commands to select the typeface are given below: 

■ b Bold 

• bi Bold alternating with italics 

• br Bold alternating with Roman 

.1 Italics 

.iB Italics alternating with bold 

• ir Italics alternating with Roman 

. rb Roman alternating with bold 

. ri Roman alternating with italics 

.SB Small alternating with bold 

• sm Small 

T raditionally, each command can have up to six arguments, buttheGN U version seems to remove this limitation. 
Arguments are delimited by spaces D ouble quotes can be used to specify an argument that contains spaces All the 
arguments will be printed next to each other without intervening spaces so that the .br command can be used to specify a 
word in bold followed by a mark of punctuation in Roman. 





Part VII: M ixdlaneous 


SECTIONS 

Sections are started with .sh followed by the heading name. If the name contains spaces and appears on the same line as .sh, 
then place the heading in double quotes T raditional headings include name, synopsis, description, options, files, see also, 
diagnostics, bugs, and author. Theonly required heading isNAME, which should befollowed on the next line by aone line 
description of the program: 

.SH NAME 

chess \- the game of chess 

It is extremely important that this format is followed and that there is a backslash before the single dash that follows the 
command name. This syntax is used by themakewhatis(8) program to create a database of short command descriptions for 
thewhatis(l) and apropos(l) commands 

OTHER MACROS 

Other macrosindudethefollowing: 

•dt Default tabs. 

.HP Begin hanging indent. 

.ip Begin paragraph with hanging tag. This is the same as .tp, except the tag is given on the 

same line not on thefollowing line. 

• lp Same as. pp. 

. pd Sdt interparagraph distance to argument. 

.pp Begin anew paragraph. 

.re End relative indent (indented paragraph). 

• rs Start relative indent (indented paragraph). 

.ss Subheading (like .sh but used for a subsection). 

.tp Begin paragraph with hanging tag. The tag is given on the next line. Thiscommand is 

similar to .ip. 

FILES 

/usr/local/lib/groff/tmac/tmac.an 
/usr/man/whatis 


SEE ALSO 

groff(l), man(l), whatis(l), apropos(l), makewhatis(8) 


Linux, 25July 1993 


signal 

signal— List of available s'gnals. 

DESCRIPTION 

Linux supports the signals listed in thissection. Several signal numbers are architecture dependent. First are the signals 

described inPOSIX.1: 

abort(3) aiarm(l) N ext various other signals 

(Here - denotes that a signal isabsent; there, where three values are given, thefirst one is usually valid for alpha and spare, 
the middle onefori386 and ppc, the last onefor mips Signal 29 issiGiNFO/siGPWRon an alpha but siglost on a spare.) 
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The letters in theAction column havethefollowing meanings: 

A D efault action isto terminatethe process. 

B Default action isto ignorethesignal. 

C D efault action isto dump core. 

D D efault action isto stop the process. 

E Signal cannot be caught. 

F Signal cannot be ignored. 

G Not a POSIX.1 conformant signal. 

CONFORMING TO 

POSIX.1 

BUGS 

sigio and siglost have the same value T he latter iscommented out in the kernel source but the build process of some 
software still thinks that Signal 29 is siglost. 

SEE ALSO 

kilL(l), kill(2), setitimer(2) 

Linux 1.3.88,14 April 1996 


suffixes 

suffixes— List of file suffixes 

DESCRIPTION 

It iscustomary to indicate the contents of a file with thefile suffix, which consists of a period followed by one or more 
letters M any standard utilities, such as compilers usethisto recognize the type of file they are dealing with. Themake(l) 
utility is driven by rules based on file suffixes. 

Following isa list of suffixes that are likely to be found on a Linux system: 


Suffix 


.C 


.[0-9]4pk 

.[1-9] 

.[l-9][a-z] 

.a 

.afm 

.arc 

arj 

.asc 


FileType 

Files for RCS (Revision Control System) 
Backup file 
C++source code 

FORTRAN source with cpp(l) directives 
Assembler source with cpp(l) directives 
Filecompressed using compress(l) 

TeX font files 

M anual page for the corresponding section 

M anual page for section plus subsection 

Static object code library 

PostScript font metrics 

ARC archive 

ARJ archive 

PGP ASCII-armored data 


continues 
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Suffix 


FileType 


.awk 

.bak 

.bm 

.c 

.cat 

.cc 

,cf 

.conf 

.config 

.cweb 

.dat 

.def 

.def 

.diff 

.doc 

.dvi 

.el 

.elc 

.eps 

,f 

.fas 

.fi 

.gif 

.gsf 

.gz 

.h 

.hip 

.htm 

.html 

.idx 

.icon 

.image 

.in 

.info 

.java 

■jpg 

.lib 

.In 

.Isp 

,m4 

.mac 


AW K language program 
Backup file 
Bitmap source 
C source 

Message catalog files 
C++source 
Configuration file 
Configuration file 
Configuration file 
Donald Knuth’sWEB for C 
Datafile 

M odula-2 source for definition modules 
Other definition files 
ASCII File differences 
D ocumentation file 
TeX device independent output 
EM ACS lisp source 
Compiled EM ACS lisp 
Encapsulated PostScript 
FORTRAN source 
Precompiled common lisp 
FORTRAN include files 
G raphics I nterchange Format 
G hostscript fonts 
Filecompressed using gzip(l) 

C or C++header files 
Help file 

HTML file imported without renaming from a brain-damaged OS 
HTML document used with the W orld W ide W eb 
C source after preprocessing 

Reference or datum-index file for hypertext or database system 
Bitmap source 
Bitmap source 

Configuration template, especially for G N U autoconf 

Files for the E M AC S info browser 

A Java source file 

JPEG compressed picture format 

lex(l) or flex(l) files 

Common lisp library 

Files for use with lint(l) 

Common lisp source 
M4(l) source 

M aero files for various programs 
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Suffix 

.man 

.me 

.mf 

.mm 

.mod 

.0 

.old 

.orig 

.out 

■P 

.patch 

■pcf 

.pfa 

.pfb 

■P9P 

.pid 

.png 

■Pi 

■pr 

■PS 

■rej 

.rules 

.s 

.sa 

.sc 

.sh 

.shar 

.so 

.sqml 

.sty 

.sym 

.tar 

.tar.Z 

.tar.gz 

.taz 

.tex 

.texi 

.texinfo 

.tfm 

■tgz 

■tmpl 


File Type 

M anual page (usually source rather than formatted) 

nrotf source using the me macro package 

M etafont (font generator for TeX) source 

Sources for groff(l) in mm format 

M odula-2 source for implementation modules 

Object file 

Old or backup file 

Backup (original) version of afilefrom patch(l) 

0 utput file often an executable program (a.out) 
Pascal source 

Filedifferencesfrom patch(l) 

Xll font files 

PostScript font definition files, ASCII format 
PostScript font definition files, binary format 
PGP binary data 

Fileto storedaemon PID (such ascrond.pid) 

Portable N etwork G raphicsfile 

Perl script 

Bitmap source 

PostScript file 

RAT FOR source (obsolete) 

Patches that patch(l) couldn't apply 
Rulesfor something 
Assembler source 

Stub libraries for a.out shared libraries 
sc( 1) spreadsheet commands 
sh(l) scripts 

Archive created by the shar(l) utility 
D LL dynamic library 
SQ M L schema or query program 
LaTeX style files 

M odula-2 compiled definition modules 
Archive created by thetar(l) utility 
tar archive compressed with compress(l) 
tar archive compressed with gztp(l) 
tar archive compressed with compressfl) 

TeX or LaTeX source 
Equivalentto .texinfo 
TeXinfo documentation source 
TeX font metrics 

tar archive compressed with gzip(l) 

Template files 


continues 
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Suffix 

FileT ype 

.txt 

Text file 

.uue 

Binary file encoded with uuencode(l) 

.web 

Donald Knuth’sWEB 

■y 

yacc(l) or bison(l) (parser generator) files 

.z 

Filecompressed using pack(l) (or an old gzip(l)) 

■ ZOO 

ZOO archive 


EM ACS or patch backup file 

rc 

Startup (run control) file, SUCh as . newsrc 


CONFORMSTO 

General UNIX conventions. 

BUGS 

This list is not exhaustive 

SEE ALSO 

filed), make(l) 


Linux, 4 April 1996 


tr2tex 

tr2tex— Convert a document from troff to LaTex 

SYNOPSIS 

tr2tex [ -in ] f i I ename 

DESCRIPTION 

tr 2 tex converts a document typeset in troff to a LaT eX format. It is intended to do thefirst pass of the conversion. The user 
should then finish up the rest of the conversion and customize the converted manuscript to his or her liking. It can also serve 
as a tutor for those who want to convert from troff to L aT eX. 

M ost of the converted document will be in LaTeX, but some of it may be in plain TeX. It will also use some macros in 
troff ms. sty or troff man. sty, which are included in the package and must be available to the document when processed with 
LaTeX. 

If there is more than one input file, they will all be converted into one LaTeX document. 

tr 2 tex understands most of the -ms and -man macrosand eqn preprocessor symbols It also understands several plain troff 
commands Few tbi preprocessor commands are understood to help convert very simple tables 
W hen converting manuals, use the -m flag. 

If a troff command cannot be converted, the line that contain that command will be commented out. 

Note that if you have eqn symbols,you must have theinline mathematics delimiter defined bydeitm inthefileyou are 
converting. If it is defined in another setup file, that setup file must be concatenated with the file to be converted; otherwise, 
tr 2 tex regards theinline math as ordinary text. 
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BUGS 

M any of these bugs are harmless Most of them cause local errors that can be fixed in the converted manuscript. 

■ Some macros and macro arguments are not recognized. 

■ Commands that are not separated from their argument by a space are not properly parsed (such as .sp3i). 

■ W hen some operators (notably over, sub, and sup) are renamed (via define) and then they are encountered in the text, 
tr 2 tex treats them as ordinary macros and does not apply their rules 

■ rpiie, lpiie, and cpiie are treated thesameascpiie. 

■ rcoi and icoi are treated thesameasccoi. 

■ M ath-mode size, gsize, fat, and gfont are ignored. 

■ uneup and mark are ignored. T he rules are so different. 

■ Sometroff commands are translated to commandsthat require delimiters that have to be explicitly put. Because they 
are sometimes not put in troff, they can create problems. Example: .nf is not closed by .fi. 

■ W hen local motions are converted to nraise or niower, an nhbox is needed, which must be put manually after the 
conversion. 

■ a sub i sub j is converted to a_i_j, which TeX parses as a_i{}j} with a complaint that it is vague, a sub {i sub j > is 
parsed correctly and converted to ajij}. 

■ Line spacing is not changed within a paragraph in TeX (which is a bad practice anyway). TeX usesthe last line spacing 
in effect in that paragraph. 


TO DO 

Access registers via the .nr command. 

SEE ALSO 

texmatch(9), trmatch(9) 

AUTHOR 

Kamal Al-Yahya, Stanford University 

1 January 1987 


Unicode 

U nicode- T he unified 16-bit super character set. 

DESCRIPTION 

The international standard ISO 10646 defines the Universal Character Sdt (UCS). UCS contains all the characters of all 
other character-set standards. It also guarantees round-trip compatibility; conversion tables can be built such that no 
information is lost when a string is converted from any other encoding to UCS and back. 

UCS contains the characters required to represent almost all known languages. This includes apart from the many languages 
that use extensions of the Latin script also thefollowing scripts and languages: Greek, Cyrillic, H ebrew, Arabic, Armenian, 
Gregorian,Japanese Chinese H iragana, Katakana, Korean, H angul, Devangari, Bengali, Gurmukhi, Gujarati, Oriya,Tamil, 
Telugu, Kannada, M alayam.Thai, Lao, Bopomofo, and a number of others. Work isgoingon to include further scripts such 
asTibetan, Khmer, Runic, Ethiopian, Hieroglyphics, various Indo-European languages, and many others. For most of these 
latter scripts, it was not yet clear how they can be encoded best when the standard was published in 1993. In addition to the 
characters required by these scripts, also a I arge number of graphical, typographical, mathematical, and scientific symbols 
such as those provided byTeX, PostScript, M S-DOS, M acintosh, Videotext, OCR, and many word processing systems have 
been included, as well as special codes that guarantee round-trip compatibility to all other existing character-set standards 
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The U C S standard (I SO 10646) describes a 31-bit character-set architecture; however, today only thefirst 65534 code 
positions (0x0000 to Oxfffd), which are called the Basic M ultilingual Plane (BM P), have been assigned characters, and it is 
expected that only very exotic characters (such as H ieroglyphics) for special scientific purposes will ever get a place outside 
this 16-bit BMP. 

T he U C S characters 0x0000 to 0x007f are identical to those of the classic U S-ASC11 character set and the characters in the 
rangeOxOOOO to OxOOff are identical to those in the I SO 8859-1 Latin-1 character set. 

COMBINING CHARACTERS 

Some code points in UCS have been assigned to combining characters These are similar to the non-spacing accent keys on a 
typewriter. A combining character just adds an accent to the previous character. T he most important accented characters 
have codes of their own in UCS; however, the combining character mechanism allows you to add accents and other 
diacritical marks to any character. The combining characters always follow the character that they modify. For example the 
German character Urnlaut-A ("Latin capital letter A with diaeresis") can either be represented by the precomposed U C S code 
0x00c4 or alternately as the combination of a normal "Latin capital letter A" followed by a "combining diaeresis"; 0x0041 
0x0308. 


IMPLEMENTATION LEVELS 

As not all systems are expected to support advanced mechanisms such ascombining characters, ISO 10646 specifies the 
following three implementation levels of U C S: 

Level 1 Combining characters and Hangul Jamo characters (a special, more complicated encoding 

of the Korean script, where H angul syllables are coded as two or three subcharacters) are not 
supported. 

Level 2 Like level 1, except in some scripts, some combining characters are now allowed (such as 

Hebrew, Arabic, Devangari, Bengali, Gurmukhi, Gujarati, Oriya,Tamil, Telugo, Kannada, 
Malayalam, Thai, and Lao). 

Level 3 All U C S characters are supported. 

TheUnicodel.l standard published by theUnicodeConsortium contains exactly the U C S Basic M ultilingual Plane at 
implementation Level 3, asdescribed in ISO 10646. Unicode 1.1 also adds some semantical defi nitionsfor some characters 
to the definitions of ISO 10646. 

UNIC0DEUNDER LINUX 

U nder Linux, only the BM P at implementation Level 1 should be used at the moment to keep the implementation 
complexity of combining characters low. The higher implementation levels are more suitable for special word processing 
formats but not asa generic system character set. The C typewchar_t ison Linux an unsigned 16-bit integer type and its 
values are interpreted asUCS Level 1 BM P codes. 

T he locale setting specifies whether the system character encoding isUTF-8 or ISO 8859-1, for example Library functions 
such aswctomb, mbtowc, orwprintf can beused to transform the internal wchar_t characters and strings into the system 
character encoding and back. 

PRIVATE AREA 

In theBM P, the range OxeOOO to 0xf8ff will never be assigned any characters by the standard and is reserved for private 
usage. For the Linux community, this private area is subdivided further into the range OxeOOO to Oxefff, which can beused 
individually by any end user and the Linux zone in the range OxfOOO to 0xf8ff where extensions are coordinated among all 
Linux users The registry of the characters assigned to the Linux zone is currently maintained by H. Peter Anvin 
(peter.Anvin@iinux.org), Yggdrasil Computing, Inc. ItcontainssomeDEC VT100 graphicscharacters missing in Unicode 
givesdirect access to the characters in the console font buffer, and containsthe characters used by a few advanced scripts such 
asKlingon. 



UTF-8 


LITERATURE 

Information technology—Universal M ultiple-Octet Coded Character Set(UCS). Part 1: Architecture and Basic M ultilingual 
Plane International Standard ISO 10646-1, International Organization for Standardization, Geneva, 1993. 

This is the official specification of UCS. Pretty official, pretty thick, and pretty expensive For ordering information, check 

The Unicode Standard- WorldwideCharacter Encoding Verson 1.0. TheUnicodeConsortium, Addison-Wesley, Reading, 
MA, 1991. 

There is already U nicode 1.1.4 available The changes to the 1.0 book are available from ftp.unicode.org. U nicode 2.0 will 
be published again as a book in 1996. 

S. H arbison.G. Steele. C , A Reference Manual. Fourth edition, Prentice H all, Englewood Cliffs, 1995, 

ISBN 0-13-326224-3. 

A good reference book about the C programming language. The fourth edition now covers also the 1994 Amendment 1 to 
thelSO C standard (ISO/IEC 9899:1990), which adds a large number of new C library functionsfor handling wide 
character sdts 

BUGS 

At the ti me when this man page was written, the Linux nbc support for U C S was far from complete. 

AUTHOR 

M arkUS Kuhn (mskuhn@cip.informatik.uni-erlangen.de) 

SEE ALSO 

utf-8(7) 

Linux, 27 December 1995 


UTF-8 

utf-8 — An ASC11-compatible multibyte U nicode encoding. 

DESCRIPTION 

T he U nicode character set occupies a 16-bit code space. The most obvious Unicode encoding (known asUCS-2) consists of 
a sequence of 16-bit words. Such strings can contain as parts of many 16-bit characters bytes such as\o or /.which have a 
special meaning in filenamesand other C library function parameters In addition, the majority of UN IX toolsexpects 
ASCII files and can't read 16-bit words as characters without major modifications. For these reasons, UCS-2 is not a suitable 
external encoding of Unicode in filenames, text files environment variables and so on. ThelSO 10646 Universal Character 
Set (U C S), a superset of U nicode, occupies even a 31-bit code space, and the obvious U C S-4 encoding for it (a sequence of 
32-bit words) has the same problems 

The UTF-8 encoding of Unicode and UCS does not have these problems and is the way to go for using the Unicode 
character set under U NI X-style operati ng systems. 

PROPERTIES 

The UTF-8 encoding has the following nice properties: 

UCS characters 0x00000000 to 0x0000007f (the classical U .S. ASC 11 characters) are encoded simply as bytes 0x00 to 0x7f 
(ASCII compatibility). This means that files and strings that contain only 7-bit ASCII characters have the same encoding 
under both ASCII and UTF-8. 

All UCS characters greater than 0x7f are encoded as a multibyte sequence consisting only of bytes in the range 0x80 to Oxfd, 
so no ASC 11 byte can appear as part of another character and there are no problems with \b or /. 
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T he lexicographic sorting order of U C S-4 strings is preserved. 

All possible2 A 31 UCS codescan be encoded using UTF-8. 

The bytes Oxfe and Oxff arenever used in theUTF-8 encoding. 

T he first byte of a multibyte sequence that represents a single non-ASC 11 U C S character is always in the range OxcO to Oxfd 
and indicates how long this multi byte sequence is. All further bytes in a multibyte sequence are in the range 0x80 to Oxbf. 
This allows easy resynchronization and makes the encoding stateless and robust against missing bytes 
U T F-8-encoded UCS characters may be up to six bytes long; however, U nicode characters can only be up to three bytes 
long. Because Linux uses only the 16-bit Unicode subset of UCS, under Linux, UTF-8 multibyte sequences can only be one 
two, or three bytes long. 

ENCODING 

Thefollowing byte sequences are used to represent a character. The sequence to be used depends on the U C S code number 
of the character: 

0X00000000 - 0X0000007F: 0*xxxxxx 
0X00000080 - 0X000007FF: 110x x x x x 10 
0x00000800 - 0X0000FFFF: 1110x x x x 10 
0x00010000 - 0x001FFFFF: 11110x x x 10 
0x00200000 - 0X03FFFFFF: 111110xx 10 
0x04000000 - 0X7FFFFFFF: 1111110X 10 

Thexxx-bit positions are filled with the bits of the character code number in binary representation. Only the shortest 
possi ble multi byte sequence that can represent the code number of the character can be used. 

EXAMPLES 

The Unicode character 0xa9 =1010 1001 (the copyright sign) isencoded in UTF-8 as 

11000010 10101001 = 0xc2 0xa9 

and character 0x2260 = 0010 0010 0110 0000 (the "not equal" symbol) is encoded as 

11100010 10001001 10100000 = 0xe2 0x89 0xa0 

STANDARDS 

ISO 10646, Unicode 1.1, XPG4, Plan 9. 

AUTHOR 

M arkUS Kuhn (mskuhn@cip.informatik.uni-erlangen.de) 

SEE ALSO 

unicode(7) 
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intro 

intro— Introduction to administration and privileged commands 

DESCRIPTION 

Thischapter describes commands that either can be or are only used by the superuser, such asdaemonsand machineor 
hardware-related commands. 

AUTHORS 

Look at the header of the manual page for the authors and copyright conditions Note that these can be different from page 
to page. 

Linux, 24 July 1993 


adduser,addgroup 

adduser, addgroup- Add a user or group to the system. 

SYNOPSIS 

adduser [--system [--home directory] [--group]] [--quiet] 
[--force-badname] [--help] [--version] [--debug] username 
adduser [--quiet] [--force-badname] [--help] [--version] 

[ - -debug ] user name group 

adduser [--group] [--quiet] [--force-badname] [--help] 
[--version] [--debug] group 


DESCRIPTION 

adduser and addgroup add users and groups to the system according to information provided in the configuration file/etc/ 
adduser. conf. adduser and addgroup automatically determine the U ID orGID and place the entity in the password or 
group file as appropriate. 

If necessary, adduser createsa home directory for the new user, copies "skeletal" user files to it from /etc/skei, and allows 
the system administrator to set an initial password and finger information for the user. 

Because it needs to be able to write to such files as /etc/passwd, adduser can only be run as root. 

G enerally, there are two types of users and groups on a system: those users that log i nto the system and those "non-user" 
accounts and groups that exist for various system tasks and projects Henceforth, user will refer to the login type and system 
user or group will refer to the type used for system maintenance and projects. 

By default, each user in Debian GN U/Linux isgiven a corresponding group with the same name and ID, allowing people 
easily to give access to their home directories to others. Thisoption can be turned off in the configuration file, in which case 
each user is by default, added to a group called users 

Linder Debian GNU/Linux, ID s less than or equal to 100 are allocated by the base system maintainer for various purposes 
IDsfrom 101 to the value specified in the configuration file ( 1000 , by default) are used for system users and groups IDs 
greater than 1000 are reserved for users and their corresponding groups. 

When invoked with a single name adduser createsa user with that name When given two names adduser assumes that the 
first name represents an existing user and that the second name represents an existing group. I n this case, the user is added to 
the group. 



OPTIONS 






- -force-badname 


- -version 

- -debug 


C reate a system user. This user will be assigned the shell /bin/false and have an 
asterisk in the password field. Unless otherwisespecified, the user will be placed 
in thegroup nogroup. Skeletal configuration files will not be copied into the 
user's home directory. 

When used with --system, thisusesdi rectory astheuser'shomedirectory, 
rather than the default specified in the configuration file If the directory does 
not exist, it is created. 

When combined with -system, a group with the same name and ID as the 
system user iscreated. If not combined with --system, a group with the given 
name is created. T his isthe default action if the program is invoked as addgroup. 


By default, user and group names are required to consist of a lowercase letter 
followed by one or more lowercase letters or numbers. T hisoption forces 
adduser or addgroup to be more lenient. 

Display brief instructions 
D isplay version and copyright information. 

D isplay a large quantity of debugging information. 


SEE ALSO 

adduser.conf(5) 

COPYRIGHT 

Copyright(c) 1995, Ted H ajek, with a great deal bo mowed from the original Debian adduser, copyright(c) 1994, Ian 
Murdock, adduser is free software; see the GN U General Public License version two or later for copying conditions There is 
no warranty. 

Debian GNU/Linux version 1.94 


agetty 

agetty— Alternative Linux getty. 

SYNOPSIS 

agetty [-ihLJ [-1 I ogi n.program] [ -m] [-t timeout] port ba ud_r at e, ... [term] 
agetty [ihL] [ -1 I ogi n.program] [-m] [ -t t i meout ] baud.rate.... port [term] 

DESCRIPTION 

agetty opens a tty port, prompts for a login name and invokes the /bin/login command. It is usually invoked by imt(8). 
agetty has several non-standard features that are useful for hard-wired and for dial-in lines: 

Adapts the tty settings to parity bits and to erase, kill, end-of-line and uppercase characters when it readsa login name 
The program can handle 7-bit characters with even, odd, none, or space parity and 8-bit characters with no parity. The 
following special characters are recognized: @ and Control-RJ (kill); #, D el and Backspace (erase); carriage return and line 
feed (end of line). 

0 ptionally deduces the baud rate from the connect messages produced by H ayes-compatible modems 
0 ptionally does not hang up when it isgiven an already opened line (useful for call-back applications). 

0 ptionally does not display the contents of the /etc/issue file (System V only). 
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Optionally invokes a non-standard login program instead of /bin/iogin. 

Optionally turns on hardware flow control. 

Optionally forces theline to be local with no need for carrier detect. 

This program does not use the /etc/gettydefs (System V) or /etc/gettytab (SunOS 4) files. 




rate,... 


A path name relative to the /dev directory. If a - is specified, agetty 
assumes that its standard input is already connected to a tty port and that 
a connection to a remote user has already been established. U nder System 
V, a - port argument should be preceded by a -. 

A comma-separated list of one or more baud rates. Each time agetty 
receives a break character, it advances through the list, which istreated as 
if it were circular. Baud rates should be specified in descending order, so 
that the null character (Ctrl+@) can also beused for baud rateavitching. 
The value to be used for the term environment variable. This overrides 
whatever intt(8) may havesdt and is inherited by login and the shell. 


Enable hardware (RTS/CTS) flow control. It is left up to the application 
to disable software (XO N /X OFF) flow protocol where appropriate. 

D o not display the contents of /etc/ issue before writing the login 
prompt. Terminals or communications hardware might become confused 
when receiving lots of text at the wrong baud rate; dial-up scripts might 
fail if thelogin prompt ispreceded by too much text. 

Invoke the specified login program instead of /bin/iogin. This allows 
the use of a non-standard login program (for example, one that asks for a 
dial-up password or that uses a different password file). 

T ry to extract the baud rate the connect status message produced by some 
H ayes-compatible modems T hese status messages are of the form: 

"< j unk><speed><j unk>". agetty assumes that the modem emits its 
status message at the same speed as specified with (thefirst) baud rate 
value on thecommand line 

Because the -m feature might fail on heavily loaded systems, you still 
should enable break processing by enumerating all expected baud rates on 
thecommand line 

Terminate if no username could be read within ti meout seconds. This 
option should probably not beused with hard-wired lines 
Forcethelineto be a local line with no need for carrier detect. This can 
be useful when you havea locally attached terminal where the serial line 
does not set the carrier detect signal. 


EXAMPLES 

T his section shows sample entries for the / etc / inittab fi le. 
For a hard-wired line: 

ttyl:con80x60:/sbin/agetty 9600 ttyl 


Foradial-in line with a 9600/2400/1200 baud modem: 

ttySI:dumb:/sbin/agetty -mt60 ttySI 9600,2400,1200 



These examples assume you usethesimpieinit(8) mit program for Linux. If you use a SysV-likeimt (does/etc/irnttab 
mention "respawn"?), refer to the appropriate manual page. 

ISSUE ESCAPES 

The/etc/issue file might contain certain escape codes to display the system name, date and time and so on. All escape 
codes consist of a backslash (\) immediately followed by one of the following letters 
b I nsert the baudrate of the current line, 

d I nsert the current date 

s I nsert the system name, the name of the operati ng system. 

1 I nsert the name of the current tty line 

m I nsert the architecture identifier of the machine, such as i486, 

n I nsert the nodename of the machine also known asthehostname 

o I nsert the domain name of the machine 

r I nsert the release number of the OS, such as 1.1.9. 

t Insert the current time, 

u I nsert the number of current users logged in. 

u I nsert the string i userorn users where n isthe number of current users logged in. 

v I nsert the version of the OS, such asthe build date and so on. 

For example, on my system, thefollowing /etc/issue file 
This is \n.\o (\s\m\r) \t 

displays as 

This is thingol.orcan.dk (Linux i386 1.1.9) 18:29:30 

FILES 

/var/run/utmp, the system status file 

/etc/issue, printed beforethe login prompt (System V only) 

/dev/consoie, problem reports (if sysiog(3) isnot used) 

/etc/inittab (Linux simpieinit(8) configuration file) 

BUGS 

T he baud-rate detection feature (the -m option) requires that agetty be scheduled soon enough after completion of a dial-in 
call (within 30ms with modems that talk at 2400 baud). For robustness, always use the -m option in combination with a 
multiple baud rate command-line argument so that break processing is enabled. 

The text in the/etc/issue file and the login prompt are always output with 7-bit characters and space parity. 

The baud-rate detection feature (the -m option) requires that the modem emits its status message after raising the DC D line. 

DIAGNOSTICS 

Depending on how the program was configured, all diagnostics are written to the console device or reported via the 
sysiog(3) facility. Error messages are produced if the port argument does not specify a terminal device, if there is no utmp 
entry for the current process (System V only), and so on. 

AUTHORS 

W.Z.Venema (wietse@wzv.win.tue.nl) Eindhoven University of Technology, Department of Mathematics and Computer 
Science Den Dolech 2, P.O. Box 513, 5600 M B Eindhoven, The Netherlands 
PdterOrbaek (poe@daimi.aau.dk), Linux port. 
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CREATION DATE 

Sat Nov25 22:51:05 M ET 1989 

LAST MODIFICATION 

91/09/01 23:22:00 

VERSION/RELEASE 

1.29 

archive 

archive- U senet article archiver. 

SYNOPSIS 

archive [ -a archive ][-f ][-i index ][-m ][-r ][i nput ] 

DESCRIPTION 

archive makes copies of files specified on its standard input. It is usually run either as a channel feed under innd(8) or by a 
script before expire(8) is run. 

archive reads the named input file or standard input if no file is given. The input is taken asa set of lines. Blank lines and 
lines starting with a number sign (#) are ignored. All other linesshould specify the name of a file to archive. If a filename is 
notan absolute pathname itis taken to be relative to /news/spooi. 

Files are copied to a directory within the archive directory, /news/spooi/news. archive. The default is to create a hierarchy 
that mimics the input files; intermediate directories are created as needed. For example the input file comp/sources/unix/ 
2211 (article 2211 in the newsgroup comp, sources. Unix) is copied to / news/spool/news, archive/comp/sources/unix/ 
2211. If the -f flag is used, then all directory names are flattened out, replacing the slashes with periods In this case the file 
is copied to /news/spool/news.archive/comp.sources.unix/2211. 

If the -i flag is used, then archive appends one line to the specified index file for each article that it copies This line 
contains the destination name and the M essage-ID and Subject headers. 

For example, a typical newsf eeds(5) entry to archive most source newsgroups isasfollows: 
source-archive\ 

:!*,‘sources*,!‘wanted*,!*.d\ 

:Tc,Wn\ 

:/archive -f -i \ 

/usr/spool/news/news.archive/INDEX 

Files are copied by making a link. If that fails a new file is created. If the -m flag is used, then the file is copied to the 
destination, and the input file is replaced with a symbolic link pointing to thenew file. The -m flag is ignored. 

By default, archive sets its standard error to /var/iog/news/erriog. To suppressthis redirection, use the -r flag. 

If the input is exhausted, archive exits with a zero status If an I/O error occurs it tries to spool its input, copying it to a file. 
If there was no in put filename, the standard input iscopied to /news/spooi/out. going/archive and the program exits. If 
an input filename was given, a temporary file named input, bch (if input isan absolute pathname) or /news/spooi/ 
out.going/input.bch (if the filename does not begin with a slash) iscreated. Once the input iscopied, archive tries to 
rename this temporary file to be the name of the input file and then exits 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet. uu. net) for InterN etN ews. 




arp 


SEE ALSO 

newsfeeds(5) 


arp 

arp- M anipulate the system ARP cache 

SYNOPSIS 

arp [-V] [-t type] -a [hostname] 
arp [ -v] -d host name ... 
arp [ -V] [-t type] -s hostname hw_addr 
arp [-v] -f f i I ename 


DESCRIPTION 

arp manipulates the kernel's ARP cache in various ways The primary options are clearing an address mapping entry and 
manually setting up one For debugging purposes, the arp program also allows a complete dump of the ARP cache 


-a [hostname ] 


Tell the user what is going on by being verbose 

When setting or reading the ARP cache this optional parameter tells arp which class 
of entries it should check for. The default value of this parameter is ether (hardware 
code 0x01 for IE E E 802.3 10M bps Ethernet). Other values might include network 
technologies such as ARC net (arcnet), PRO net (pronet), and AX.25 (ax25). 

Shows the entries of the specified hosts. If thehost name parameter is not used, all 
entries are displayed. 

Remove the entries of the specified host. This can be used if the indicated host is 
brought down, for example 

M anually create an ARP address mapping entry for host host name with hardware 
address set to h #_ a d d r. T he format of the hardware address is dependent on the 
hardware class, but for most classes, you can assume that the usual presentation can 
be used. For the Ethernet class, this issix bytes in hexadecimal, separated by colons 
Similar to the -s option, only th is time the address info is taken from file f i i ename. 

T his can be used if ARP entries for a lot of hosts have to besdt up. The name of the 
data file is often /etc/ethers, but this is not official. 

The format of the file is simple; it only contains ASCI I text lines with a hostname 
and a hardware address separated by whitespace. 


In all places where a hostname isexpected, you can also enter an IP addressin dotted-decimal notation. 


FILES 

/proc/net/arp 

/etc/ethers 


AUTHOR 

Fred N . van Kempen (waltje@uwalt.nl.mugnet.org) 
09 June 1994 
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badblocks 

badbiocks— Search a device for bad blocks. 

SYNOPSIS 

badblocks [ -b block-size ] [ -o out put _f i I e ] [ -v ][-w ] device blocks-count 

DESCRIPTION 

badblocks isused to search for bad blocks on a device (usually a disk partition), device isthe special file corresponding to the 
de/ice (such as/dev/hdxx). biocks-count isthe number of blocks on the device. 

OPTIONS 

-b block-size Specify thesize of blocks in bytes 

-o output.fi i e W ritethe list of bad blocks to the specified file. Without thisoption, badblocks 

displaysthe list on its standard output. 

-v Verbose mode. 

-w Use write-mode test. With thisoption, badblocks scansfor bad blocks by writing 

some patterns (Oxaa, 0x55, Oxff, and 0x00) on every block of the device, reading 
every block and comparing the contents 

WARNING 

Never use the -w option on a device containing an existing filesystem. Thisoption erases data! 

AUTHOR 

badblocks was written by RemyCard (card@masi.ibp.fr), the developer and maintainerof theext 2 fs. 

BUGS 

I had no chance to make real tests of this program because I use IDE drives, which remap bad blocks I only made some tests 
on floppies 

AVAILABILITY 

badblocks is available for anonymous FTP from ftp.ibp.fr and tsx-11 .mit. edu in / pub / linux / packages/ext2f s. 

SEE ALSO 

e2fsck(8), mke2fs(8) 

Verson 0.5b, N ovember 1994 


buffchan 

buff chan- Buffered file-writing back end for InterN dtN ews. 

SYNOPSIS 

buffchan [ -b ][ -c I i nes ] [-C seconds ][-d directory ] 

[-f fields ][-m map ][-p pidflle ][ -1 lines ][ -L seconds ] 
l-r ][ -s file.format ][-u ] 

DESCRIPTION 

buffchan reads lines from standard input and copies certain fields in each line into files named by other fields within the 
line buffchan isintended to be called by innd(8) as an exploder feed. 



cfdisk 


buff chan input is interpreted as a set of lines. Each linecontainsa fixed number of initial fields, followed by a variable 
number of filename fields All fields in a line are separated by whitespace The default number of initial fields is one the-f 
flag may be used to specify a different number of fields See fiiechan(8) for an example. 

After the initial fields, each remaining field names a file to write The - s flag may beused to specify a format string that maps 
the field to a filename Thisisasprintf(3) format string, which should have a single %s parameter that is given the field. 
Thedefault value is/news/spooi/out. going/%s. See the description ofthisflagin fiiechan(8).The-dflagmay beused to 
specify a directory the program should change to before starting. If this flag is used, then thedefault for the-s flag is 
changed to be a simple %s. 

Once buff chan opens a file it keeps it open. The input must therefore never specify more files than the number of available 
descriptorscan keep open. If the -b flag is used, the program will allocate a buffer and attach it to the file using setbuf(3). If 
the -u flag is used, the program will request unbuffered output. 

If the -l flag is used with a number n, then buff chan will call ffiush(3) after every n lines are written to a file If the -c flag 
is used with a number n, then buff chan will close and reopen, a file after every n lines are written to a file. 

If the -l flag is used with a number n, then all files will be flushed every n seconds. Similarly, the-c flag may beused to 
specify that all files should be closed and reopened every n seconds 

By default, the program sets its standard error to /var/iog/news/erriog. To suppress this redirection, use the -r flag. 

If the -p flag is used, the program will write a line containing its process ID (in text) to the specified fi le. 

buff chan can be invoked as an exploder feed (see newsf eeds(5)). As such, if a line starts with an exclamation point, it is 

treated as a command. There are three commands: 

flush The flush command dosesand reopensall open files; flush xxx flushes only the 

specified site. These are analogous to thectiinnd(8) flush command and can be 
achieved by doing a send flush xxx command. Applications can tell that theflush 
has completed by renaming thefile before issuing the command; buff chan has 
completed the command when the original filename reappears, 
buff chan also changes the access permissions of thefile from read-only for everyone 
to read-write for owner and group as it flushes or closes each output file. It changes 
the modes back to read-only if it reopens the same file 

drop T he drop command is similar to the flush command except that any files are not 

reopened. If given an argument, then the specified site is dropped; otherwise, all sites 
are dropped. (Note that the site will be restarted if theinput stream mentionsthe 
site.) When a ctiinnd "drop site" command is sent, innd will automatically forward 
the command to buff chan if the site is a funnel that feeds into this exploder. T o 
drop all sites, use the ctiinnd send buffchan-site dropcommand. 
readmap The map file (specified with the -m flag) is reloaded. 

HISTORY 

Written by Rich $alz(rsaiz@uunet.uu.net)forlnterNdtN ews. 

SEE ALSO 

ctlinnd(8), f ilechan(8), innd(8), newsf eeds(5). 

cfdisk 

cfdisk— Curses-based disk partition table manipulator for Linux. 

SYNOPSIS 

cfdisk [ -avz ] [ -c cylinders ][-h heads ] [-s sectors-per-1 r ack ][ -P opt ] 

[device ] 
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DESCRIPTION 

cfdisk isacurses-based program for partitioning a hard disk drive. The device can beany one of the following: 

/dev/hda [default] 

/dev/hdb 

/dev/sda 

/dev/sdb 

/dev/sdc 

/dev/sdd 

cfdisk first tries to read the geometry of the hard disk. If it fails, an error message is displayed and cfdisk exits. This should 
only happen when partitioning a SCSI drive on an adapter without a BIO S. To correct this problem, you can set the 
cylinders, heads, and sectors-per-track on thecommand line N ext, cfdisk tries to read the current partition table from the 
disk drive If it is unable to figure out the partition table, an error is displayed and the program exits This might also be 
caused by incorrect geometry information and can be overridden on thecommand line Another way around this problem is 
with the -z option. This will ignore the partition tableon thedisk. 

The main display is composed of four sections, from top to bottom: the header, the partitions thecommand line and a 
warning line. The header contains the program name and version number followed by the disk drive and its geometry. The 
partitions section always displays the current partition table. Thecommand line is the place where commands and text are 
entered. The available commands are usually displayed in brackets. The warning line is usually empty except when there is 
important information to be displayed. The current partition is highlighted with reverse video (or an arrow if the - a option 
is given). All partition-specific commands apply to the current partition. 

The format of the partition table in the partition's section is, from left to right: Name, Flags, Partition Type, Filesystem 
Type, and Size The name is the partition device name Theflagscan be Boot, which designates a bootable partition or NC, 
which stands for "Not Compatible with DO SorOS/2." DOS, OS/2, and possibly other operating systems require the first 
sector of thefirst partition on thedisk and all logical partitions to begin on the second head. Thiswastes the second through 
the last sector of thefirst track of thefirst head (thefirst sector is taken by the partition table itself), cfdisk allows you to 
recover these "lost" sectors with the maximize command (m). N ote that f disk(8) and some early versions of D 0 S create all 
partitions with the number of sectors already maximized. For more information, see the maximize command later in this 
chapter. The partition type can be primary or Logical. For unallocated space on the drive, the partition type can also be 
pn/Log or empty (if the space is unusable). The filesystem type section displays the name of the filesystem used on the 
partition, if known. If it is unknown, then Unknown and the hex value of the filesystem type are displayed. A special case 
occurs when there are sections of the disk drive that cannot be used (because all the primary partitions are used). When this 
isdetected, thefilesystem typeisdisplayed as unusable. Thesize field displays the size of the partition in megabytesfby 
default). It can also display the size in sectors and cylinders (see the changeunits command later in this chapter). If an 
asterisks (*) appears after the size this means that the partition is not aligned on cylinder boundaries. 

DOS 6Jf WARNING 

TheDOS 6.x format command looksfor some information in thefirst sector of the data area of the partition and treats this 
information as more reliable than the information in the partition table, dos format expects dos fdisk to clear thefirst 512 
bytes of the data area of a partition whenever a size change occurs dos format looks at thisextra information even if the /u 
flag is given; we consider this a bug in dos format and dos fdisk. 

The bottom line is that if you use cfdisk or fdisk to change the size of a DOS partition table entry and then you must also 
usedd to zero thefirst 512 bytes of that partition before using dos format to format the partition. For example if you were 
using cfdisk to make a D 0 S partition table entry for /dev/hdai, then (after exiting fdisk or cfdisk and rebooting Linux 
so that the partition table information isvalid), you use the command dd if=/dev/zero of=/dev/hdai bs=si2 counts to 
zero thefirst 512 bytes of the partition. 

Be extremely careful if you use the dd command because a small typo can make all of the data on your disk useless 
For best results you should always use an 0 S-specific partition table program. For example, you should make DOS 
partitions with the dos fdisk program and Linux partitions with the Linux fdisk or Linux cfdisk program. 



cfdisk 


COMMANDS 

cfdisk commands can be entered by pressing the desired key (pressing Enter after the command is not necessary). H ere is a 

list of the available commands: 

b Toggle bootable flag of the current partition. This allows you to select which primary partition is 

bootable on the drive. 

d D elete the current partition. T his will convert the current partition into free space and merge it 

with any free space immediately surrounding thecurrent partition. A partition already marked as 
free space or marked as unusable cannot be deleted. 

g Changethedisk geometry (cylinders, heads orsectors-per-track). Warning: Thisoption should 

only be used by people who know what they are doing. A command-line option is also available to 
changethedisk geometry. While at the change disk geometry command line, you can choose to 
change cylinders (d), heads (h), and sectors per track (s). T hedefault value will be printed at the 
prompt, which you can accept by simply pressing the Enter key or you can exit without changes by 
pressing the Esc key. If you want to change the default value simply enter the desired value and 
press E nter. T he altered disk parameter values do not take effect until you return to the mai n menu 
(by pressing Enter or Esc at the change disk geometry command line If you change the geometry 
such thatthedisk appears larger, the extra sectors are added attheend of thedisk as free space If 
the disk appears smaller, the partitions that are beyond the new last sector are deleted and the last 
partition on the drive (or the free space at the end of thedrive) is made to end at the new last 
sector. 

h Print the help screen. 

m M aximizedisk usage of the current partition. Thiscommand will recover the the unused space 

between the partition table and the beginning of the partition, at the cost of making the partition 
incompatible with DOS, OS/2, and possibly other operating systems Thisoption will toggle 
between maximal disk usage and DOS, OS/2, and so on compatible disk usage. The default when 
creating a partition is to create D 0 S, 0 S/2, and so on compatible partitions 

n Create new partitionsfrom free space. If the partition type is Primary or Logical, a partition of 

that type will be created, but if the partition type is Pri/Log, you will be prompted for the type you 
want to create. Be aware that there are only four slots available for primary partitions and because 
there can be only one extended partition that contains all of the logical drives, all of the logical 
drives must be contiguous (with no intervening primary partition), cfdisk next prompts you for 
the size of the partition you want to create. The default size, equal to the entire free space of the 
current partition, isdisplayed in megabytes. You can either press theEnter key to accept the default 
size or enter a different size at the prompt, cfdisk accepts size entries in megabytes (m) (default), 
kilobytes (k), cylinders (d), and sectors (s) when you enter the number immediately followed by m, 
k, c, or s. If the partition fills the free space avail able the partition iscreated and you are returned 
to the main command line. Otherwise the partition can be created at the beginning or the end of 
thefree space and cfdisk will ask you to choose where to place the partition. After the partition is 
created, cfdisk automatically adjusts the other partition's partition types if all of the primary 
partitions are used. 

p Print the partition table to the screen or to a file. There are several different formats for the 

partition that you can choose from: 

r Raw data format (exactly what would be written to disk). 

s Partition table in sector order format. 

t Partition table in raw format. The raw data format will print the sectors that would bewritten to 

disk if a write command isselected. First, the primary partition table is printed, followed by the 
partition tables associated with each logical partition. The data is printed in hex byte-by-byte with 
16 bytes per line The partition table in sector order format will print the partition table ordered by 
sector number. The fields, from left to right, are the number of the partition, the partition type, the 
first sector, the last sector, the offset from the first sector of the partition to the start of the data, the 
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length of the partition, thefilesystem type (with the hex value in parentheses), and the flags (with 
the hex valuein parentheses). In addition to the primary and logical partitions, free and unusable 
space is printed and the extended partition isprinted before the first logical partition. 

If a partition does not start or end on a cylinder boundary or if the partition length is not divisible 
by the cylinder size, an asterisk (*) isprinted after the non-aligned sector number/count. This 
usually indicates that a partition was created by an operating system that either does not align 
partitions to cylinder boundaries or that used different disk geometry information. If you know the 
disk geometry of the other operating system, you can enter the geometry information with the 
change geometry command (g). 

For thefirst partition on the disk and for all logical partitions, if the offset from the beginning of 
the partition is not equal to the number of sectors per track (that is, the data does not start on the 
first head), a number sign (#) isprinted after the offset. For the remaining partitions, if the offset is 
not zero, a number sign isprinted after the offset. This corresponds to the nc flag in the partitions 
section of the main display. 

The partition table in raw format will print the partition table ordered by partition number. It will 
leave out all free and unusable space. The fields, from left to right, are the number of the partition, 
theflags (in hex), the starting head, sector, and cylinder, thefilesystem ID (in hex), the ending 
head, sector, and cylinder, the starting sector in the partition, and the number of sectors in the 
partition. The information in thistablecan be directly translated to the raw data format. The 
partition table entries only have 10 bits avail able to represent the starting and ending cylinders 
Thus, when the absolute starting (ending) sector number is on a cylinder greater than 1023, the 
maximal values for starting (ending) head, sector, and cylinder are printed. This isthe method used 
by OS/2, and it fixes the problems associated with OS/2'sf disk rewriting the partition table when 
it isnot in this format. Because Linux and 0 S/2 use absolute sector counts, the values in the 
starting and ending head, sector, and cylinder are not used, 
q Q uit program. Thiswill exit the program without writing any data to disk, 

t Change the filesystem type. By default, new partitionsare created as Linux partitions, but because 

cf disk can create partitionsfor other operating systems, changing the partition type allows you to 
enter the hex value of thefilesystem you desire. A list of the known filesystem types is displayed. 
You can type the filesystem type at the prompt or accept the default filesystem type (Linux), 
u Change units of the partition size display. It will rotate through megabytes, sectors, and cylinders 

w W rite partition table to disk (you must enter an uppercase w). Because this might destroy data on 

the disk, you must either confirm or deny the write by entering yes or no. If you enter yes, cf disk 
will write the partition table to disk and the tell the kernel to re-read the partition table from the 
disk. The re-reading of the partition table works in most cases but I have seen it fail. Don't panic. 

It will be correct after you reboot the system. In all cases I still recommend rebooting the sykem 
just to be safe. 

Up arrow, Down arrow M ove cursor to the previous or next partition. If there are more partitions than can be displayed on 
a screen, you can display the next (previous) set of partitions by moving down (up) at the last (first) 
partition displayed on thescreen. 

Ctrl+L Redraws the screen. I n case something goes wrong and you cannot read anything, you can refresh 

the screen from the main command line. 

? Print the help screen. 

All the commands can be entered with either uppercase or lowercase letters (except for writes). When in a submenu or at a 
prompt to enter a filename, you can hit the Esc key to return to the main command line. 

OPTIONS 

- a U se an arrow cursor instead of reverse video for highlighting the current partition. 

-v Print the version number and copyright. 




chat 


Start with zeroed partition table. This option is useful when you want to repartition 
your entire disk. N ote that this option does not zero the partition table on the disk; 
rather, it simply starts the program without reading the existing partition table. 


-s sectors-per-track Override the number of cylinders, heads, and sectors-per-track read from the BIOS. If 

your BIO S or adapter does not supply this information or if it supplies incorrect 
information, use these options to set the disk geometry values 
-p opt Printsthe partition table in specified formats opt can be one or more of r, s, or t. See 

the print command for more information on the print formats 


SEE ALSO 

fdisk(8) 

BUGS 

The current version does not support multiple disks (future addition). 

AUTHOR 

Kevin E. M artin (martin@cs.unc.edu) 

TheBOGUSLinuxReleas, 3 Junel995 


chat 

chat— Automated conversational script with a modem. 

SYNOPSIS 

chat [ opti ons ] scri pt 


DESCRIPTION 

The chat program defines a conversational exchange between the computer and the modem. Its primary purpose is to 
establish the connection between the Point-to-Point protocol daemon (pppd) and the remote's pppd process 


OPTIONS 


Read the chat script from the chat file T he use of this option is mutually exclusive with 
the chat script parameters The user must have read access to the file M ultiple lines are 
permitted in the file Space or horizontal tab characters should be used to separate the 
strings. 

Set the timeout for the expected string to be received. If the string is not received 
within the time limit, then the reply string is not sent. An alternate reply may be sent or 
the script will fail if there is no alternate reply string. A failed script will cause the chat 
program to terminate with a nonzero error code. 

Set the file for output of the report strings Ifyou use the keyword report, the resulting 
strings are written to thisfile. If this option is not used and you still use report 
keywords the stderr file is used for the report strings. 

Request that thechat script be executed in a verbose mode The chat program will then 
log all text received from the modem and the output strings that it sends to thesYSLOG. 
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-v Request that thechat script be executed in a stderr verbose mode The chat program 

will then log all text received from the modem and the output strings that it sends to the 
stderr device. T hisdevice is usually the local console at the station running the chat or 
pppd program. Thisoption does not work properly if the stderr is redirected to the / 
dev/nuii location becausein that case pppd should run in the detached mode. In that 
case use the -v option to record the session on the syslog device, 
script If the script is not specified in a file with the -f option, then the script is included as 

parametersto the chat program. 

CHAT SCRIPT 

The chat script defines the communications 

A script consists of one or more"expect-send" pairs of strings separated by spaces, with an optional "subexpect-subsend" 
string pair, separated by a dash as in thefollowing example: 

ogin:-BREAK-ogin: ppp ssword: hello2u2 

This line indicates that the chat program should expect the string ogin:. If i t fails to receive a login prompt within the time 
interval allotted, it is to send a break sequence to the remote and then expect the string ogin:. If the first ogin: isreceived, 
then the break sequence is not generated. 

0 nee it receives the login prompt, the chat program will send the string ppp and then expect the prompt ssword:. W hen it 
receives the prompt for the password, it will send the password heiio2u2. 

A carriage return is usually sent following the reply string. 11 is not expected in the "expect" string unless it is specifically 
requested by using the nr character sequence. 

The expect sequence should contain only what is needed to identify the string. Because it is usually stored on a disk file it 
should not contain variable information. It is generally not acceptable to look for time strings, network identification strings, 
or other variable pieces of data such as an expect string. 

To help correct for characters that may be corrupted during the initial sequence look for the string ogin: rather than 
login:. It is possiblethat the leading 1 character might be received in error and you might never find the string even though 
it was sent by the system. For this reason, scripts look for ogin: rather than login: and ssword: rather than password:. 

A very simple script might look like this: 
ogin: ppp ssword: hello2u2 

In other words, expect... .ogin:, send ppp, expect.. .ssword:, send heiio2u2. 

In actual practice, simple scripts are rare. At the vary least, you should include subexpect sequences in case the original string 
is not received. For example, consider thefollowing script: 

ogin:-ogin: ppp ssword: hello2u2 

T his is a better script than the si mple one used earl i er. T his looks for the same login: prompt; however, if one was not 
received, a single return sequence is sent and then it will look for login: again. Should line noise obscure the first login 
prompt then sending the empty line will usually generate a login prompt again. 

ABORT STRINGS 

M any modems will report the status of the cal I as a string. These strings may be connected or no carrier or busy. It is 
often desirable to terminate the script if the modem fails to connect to the remote. The difficulty is that a script does not 
know exactly which modem string it might receive 0 n oneattempt, it might receive busy, but the next time, it might 
receive no carrier. 

These "abort" strings can be specified in the script using the abort sequence. It is written in the script as in thefollowing 
example: 



ABORT BUSY ABORT 'NO CARRIER' " ATZ OK ATDT5551212 CONNECT 



This sequence will expect nothing and then send the string ATZ. The expected response to this isthe string ok. When it 
recei ves ok, the string ATDT5551212 dials the telephone. The expected string is connect. If thestring connect is received, the 
remainder of the script is executed. H owever, if the modem finds a busy telephone, it sends the string busy. This causes the 
string to match the abort character sequence. The script then fails because it found a match to the abort string. If it received 
thestring no carrier, it aborts for the same reason. Either string may be received. Either string will terminate the chat 
script. 

REPORT STRINGS 

A report string issimilar to theABORT string. The difference isthat the strings and all characters to the next control character 
such as a carriage return, are written to the report file. 

T he report strings may be used to isolate the transmission rate of the modem's connect string and return the value to the chat 
user. The analysis of the report string logic occurs in conjunction with the other string processing such as looking for the 
expect string. The use of the same string for a report and abort sequence is probably not very useful; however, it is possible. 
The report strings do not change thecompletion code of the program. 

These "report" strings may be specified in the script using theREPORT sequence It is written in thescript as in thefollowing 
example; 

REPORT CONNECT ABORT BUSY " ATDT5551212 CONNECT " ogin: account 

This sequence expects nothing and then sends the string atdtsssi 212 to dial the telephone Theexpected string iscoNNECT. 

If the string connect is received, the remainder of the script is executed. I n addition, the program writes to the expect-file the 
string connect plus any characters that follow it such as the connection rate. 

TIME-OUT 

Theinitial timeout value is 45 seconds. This may be changed using the -t parameter. 

T 0 change the timeout value for the next expect string, thefollowing example may be used: 

ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:-ogin: TIMEOUT 5 password:: hello2u2 

This changes the timeout to 10 seconds when it expects the login: prompt. The timeout is then changed to 5 seconds 
when it looks for the password prompt. 

The timeout, once changed, remains in effect until it is changed again. 

SENDING EOT 

The special reply string of eot indicates that the chat program should send an eot character to the remote. This is usually the 
End-of-file character sequence. A return character is not sent following the eot. T he eot sequence may be embedded into the 
send string using the sequence -d. 

GENERATING BREAK 

The special reply string of break causes a break condition to be sent. The break is a special signal on the transmitter. The 
normal processing on the receiver isto change the transmission rate. It may be used to cycle through the available transmis¬ 
sion rates on the remote until you are able to receive a valid login prompt. The break sequence may be embedded into the 
send string using the \k sequence 

ESCAPE SEQUENCES 

The expect and reply strings may contain escape sequences. All the sequences are legal in the reply string. Many are legal in 
the expect. Those that are not valid in the expect sequence are so indicated. 

11 Expects or sends a null string. If you send a null string, it will still send the return 

character. This sequence may either be a pai r of apostrophe or quote characters. 

\ \ b Represents a backspace character. 
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\\c Suppresses the newline at the end of the reply string. This is the only method to send a 

string without a trailing return character. It must be at the end of the send string. For 
example, thesequenceheiio\c will simply send the characters h, e, x, 1, o. (Not valid in 
expect.) 

\\d Delay for one second. The program usessieep(l), which will delay to a maximum of 

onesecond. (N ot valid in expect.) 

\\k Insert a break. (Not valid in expect.) 

\\n Send a newlineor linefeed character. 

\\n Send a null character. The same sequence may be represented by \@. (Not valid in 

expect.) 

Up Pausefor a fraction of a second. The delay is one tenth of a second. (Not valid in 

expect.) 

\\q Suppress writing the string to the syslog file. The string ?????? is written to the log in 

its place (Not valid in expect.) 

\\r Send or expect a carri age return. 

\\s Represents a space character in the string. This may be used when it is not desirableto 

quote the strings that contains spaces. Thesequence hi Tiwiand Hi\sTiMarethesame 

\ \ t Send or expect a tab character. 

\ \ \ \ Send or expect a backslash character. 

uddd Collapsetheoctal digits (ddd) into a single ASCI I character and send that character. 

(Some characters are not valid in expect.) 

-c Substitute the sequence with thecontrol character represented bye. For example the 

character dci (17) isshown as "q. (Some characters are not valid in expect.) 


TERMINATION CODES 

The chat program will terminate with thefollowing completion codes: 

0 The normal termination of the program. This indicates that the script was executed 

without error to the normal conclusion. 

1 One or more of the parameters are invalid or an expect string was too largeforthe 
internal buffers. This indicates that the program as not properly executed. 

2 An error occurred during the execution of the program. This may be due to a read or 
write operation failing for some reason or chat receiving a signal such assiGiNT. 

3 A time-out event occurred when there was an expect string without having a - subsend 
string. This may mean that you did not program the script correctly for the condition or 
that some unexpected event occurred and the expected string could not be found. 

4 Thefirst string marked as an abort condition occurred. 

5 Thesecond string marked asan abort condition occurred. 

6 The third string marked asan abort condition occurred. 

7 The fourth string marked asan abort condition occurred. 

The other termination codesarealso stringsmarked asan abort condition. 

Using the termination code it is possible to determine which event terminated the script. It is possible to decide if the string 
busy was received from the modem asopposed to no dial tone. Although thefirst event may be retried, thesecond will 
probably have little chance of succeeding during a retry. 

SEE ALSO 

Additional information about chat scripts may be found with UUCP documentation. The chat script was taken from the 
ideas proposed by the scripts used by the uucico program. 
uucico(l), uucp(l) 




dock 


COPYRIGHT 

The chat program is in public domain. This is not the GN U public license. If it breaks, then you get to keep both pieces 

Chat Version 1.9,5 May 1995 


chroot 

chroot— C hange root directory and execute a program there. 

SYNOPSIS 

chroot directory program [ arg ... ] 

DESCRIPTION 

chroot changes the root directory for a process to a new directory executes a program there. 

SEE ALSO 

chroot(2) 

AUTHOR 

Rick Sladkey (jrs@world.std.com) 

Linux0.99, 20 N member 1993 


clock 

clock— M anipulate the C M 0 S clock. 

SYNOPSIS 

/sbin/clock [ -u ] -r 

/sbin/clock [ -u ] -w 

/sbin/clock [ -u ] -s 

/sbin/clock [ -u ] -a 

DESCRIPTION 

clock manipulates theC M 0 S clock in variousways, allowing it to be read or written and allowing synchronization between 
the C M 0 S clock and the kernel's version of the system time. 

OPTIONS 

- U I ndicates that the C M 0 S clock is set to U ni versal Time. 

- r Read C M 0 S clock and print the result to stdout. 

-w Write the system timeintotheCM OSdock. 

-s Set thesystemtimefromtheCM OSdock. 

- a Set the system time from the C M 0 S clock, adjusting the time to correct for systematic 

error and writing it back into theCM OSdock. This option uses the file/etc/ad j time 
to determinehow the clock changes. It contains three numbers. 

The first number is the correction in seconds per day. (For example, if your clock runs 5 
seconds fast each day, the first number should read -5.0.) 

The second number tells when clock was last used in secondssince 1/1/1970. 

The third number is the remaining part of a second that was leftover after the last 
adjustment. 
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Thefollowing instructions are from the source code: 

1. Createafile/etc/adjtimecontainingasthefirstandonlylineo.o 0 0.0. 

2. Run clock -auorclock -a.dependingonwhdtheryourCMOSisinUniversalorLocalTimeThisupdatesthe 
second number. 

3. Set your system time using the date command. 

4. Update your CM OS time using clock -wu or clock -w. 

5. Replacethefirst number in /etc/adj time by your correction. 

6. Put the command clock -au or clock -a in your /etc/rc. local or let cron(8) start it regularly. 

FILES 

/etc/adjtime 
/etc/rc.local 

AUTHORS 

Vl.O 
Vl.l 
VI.2 


comsat 

comsat-Biff server 

SYNOPSIS 

comsat 

DESCRIPTION 

comsat isthe server process that receives reports of incoming mail and notifies users if they requested this service comsat 
receives messages on a datagram port associated with the biff service specification (seeservices(5) and inetd(8)). The one- 
line messages are of the form 


If the user specified is logged in to the system and the associated terminal has the owner execute bit turned on (by a biff y), 
the offset is used as a seek offset into the appropriate mailbox file and the first 7 lines or 560 characters of the message are 
printed on the user's terminal. Lines that appear to be part of the message header other than the From, To, Date, or Subject 
lines are not included in thedisplayed message. 

FILES 

/var/ run/utmp to find out who's logged on and on what terminals 

SEE ALSO 

biff (1), inetd(8) 

BUGS 

The message header filtering is prone to error. The density of the information presented is near the theoretical minimum. 
Users should be notified of mail that arrives on other machines than the one to which they are currently logged in. 

The notification should appear in a separate window so it does not mess up the screen. 


C harles H edrick (hedrickiacs. rutgers. edu) Apr 1992 
M odified for clock adjustments, Rob H ooft (hoof t@chem.ruu.ni) Nov 1992 
Patchesby H arald Koenig(koenig@nova.tat.physik.uni-tuebingen.de) applied by 
Rob H ooft (hoof t@EMBL - Heidelberg. DE) 0 Ct 1993 

Linux0.99, 24 December 1992 
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HISTORY 

The command appeared in BSD 4.2. 



BSD 4.2,16 M arch 1991 


crond 

crond—cron daemon (Dillon’sCron). 

SYNOPSIS 

crond [-1#] [-d[#]] [ -f ] I -bj [-c directory] 

OPTIONS 

crond is a background daemon that parses individual crontab files and executes commands on behalf of the users in 
question. 

-li ogi evei Set logging level; default is8. 

-d[debugi evei ] Set debugging level; default iso. If no level is specified with the -d option, the default is 

i. This option also sets the logging level to o and causes crond to run in theforeground. 
-t Run crond in theforeground. 

-b Run crond in the background (the default unless -d isspecified). 

-c directory Specify directory containing crontab files. 

DESCRIPTION 

crond is responsible for scanning the crontab files and running their commands at the appropriate ti me T he crontab 
program communicates with crond through the cron, update file, which resides in the crontabs directory, usually /va n 
spooi/cron/crontabs. This is accomplished by appending thefilename of the modified or deleted crontab file to 
cron, update, which crond then picks upto resynchronize or remove its internal representation of thefile. 
crond has a number of built-in limitations to reduce the chance of it being ill-used. Potentially infinite loops during parsing 
aredealt with via a failsafe counter, and user crontabs are generally limited to 256 crontab entries crontab lines may not 
be longer than 1024 characters including the newline 

Whenever crond must run a job, it first creates a daemon-owned temporary file o_excl and o_APPENDto store any output, 
and then itforkosand changes its user and group permissionsto match that of the user the job is being run for. Then, it 
executes /btn/sh -c to run thejob. T hetemporary file remains under theownership of the daemon to prevent the user from 
tampering with it. U pon job completion, crond verifies the secureness of the mail file and, if it has been appended to, mails 
to the file to user. The sendmaii program is run under the user's UID to prevent mail-related security holes. U nlike 
crontab, the crond program does not leave an open descriptor to the file for the duration of the job's execution because this 
might cause crond to run out of descriptors. When the crontab program allows a user to edit his crontab, it copies the 
crontab to a user-owned file before running the user's preferred editor. Thesuid crontab program keeps an open 
descriptor to thefile which it later uses to copy thefile back, thereby ensuring the user has not tampered with the file type 
crond alwayssynchronizesto the top of the minute checking the current time against the list of possiblejobs. T he list is 
stored such that the scan goes very quickly, and crond can deal with several thousand entries without taking any noticeable 
amount of CPU. 

AUTHOR 

M atthew Dillon (dillon@apollo.west.oic.com) 


1 May 1994 
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ctlinnd 

ctiinnd—Control the InterN etN ewsdaemon. 

SYNOPSIS 

ctlinnd [ -h ][-s ][-t timeout ] command [ argument ... ] 

DESCRIPTION 

ctiinnd sends a message to the control channel of innd(8), the I nterN etN ews server. 

In the normal mode of behavior, the message is sent to the server, which then performs the requested action and sends back a 
reply with a text message and the exit code for ctiinnd. If the server successfully performed the command, ctiinnd will exit 
with a status of zero and print the reply on standard output. If the server could not perform the command (for example it 
was told to remove a newsgroup that does not exist), it will direct ctiinnd to exit with a status of one. The shutdown, 
xabort, and xexec commands do not generate a reply; ctiinnd will always exit silently with a status of zero. If the -s flag is 
used, then no message will be printed ifthecommand was successful. 

T he-t flag can be used to specify how long to wait for the reply from the server. The timeout value specifies the number of 
seconds to wait. A value of zero waits forever, and a value less than zero indicates that no reply isneeded. When waiting for a 
reply, ctiinnd will try every two minutes to see if the server is still running, so it is unlikely that-to will hang. The default 
is-to. 


To see a command summary, use the-h flag. If acommand isincluded when ctiinnd isinvoked with the-h flag, then only 

the usage for that command will be given. 

If a large number of groups are going to be created or deleted at once, it may be more efficient to pause or throttle the server 

and edit the active file directly. 

The complete list of commands follows Note that all commands have a fixed number of arguments. If a parameter can bean 

empty string, then it is necessary to specify it as two adjacent quotes (■"). 

addhistMess age-1 Dar r exp post paths Add an entry to the history database Thisdirectstheserverto createa 

history line for M essage-ID. T he angle brackets are optional, arr, exp, and 
post specify when the article arrived, what its expiration dateis, and when it 
was posted. All three values are a number indicating the number of seconds 
si nee the epoch. If the article does not have an Expires header, then exp 
should be zero, paths isthe pathname within thenewsspool directory where 
thearticle isfiled. If the article is cross-posted, then the names should be 
separated by whitespace and the pat hs argument should be inside double 
quotes. If the server is paused or throttled, this command causes it to briefly 
open the history database 

allow reason Remote connections are allowed. The reason must bethesametext given 

with an earlier reject command or an empty string. 

begin site Begin feeding si te. T his will cause the server to rescan the newsf eeds(5) file 

to find the specified site and set up a newsfeed for it. If the site already exists, 
a "drop" isdonefirst. Thiscommand isforwarded; see below. 

cancel <Message-iD> Remove the article with the specified M essage-ID from the local system. This 

does not generate a cancel message. T he angle brackets are optional. I f the 
server is paused or throttled, thiscommand causes it to briefly open the 
history database. 

changegroup group rest Thenewsgroup group is changed so that itsfourth field in the active file 

becomes the value specified by the rest parameter. This may be used to make 
an existing group moderated or unmoderated, for example. 

checkf lie C heck the syntax of the newsfeeds file, and display a message if any errors are 

found. T he details of the errors are reported to sysiog(3). 




ctlinnd 


1277 


flushlogs 


hangup channel 
help [command] 


newgroup group rest creator 


Flush and drop site from the server's list of active feeds. This command is 
forwarded; see below. 

F lush the buffer for the specified s i t e . T he actions taken depend on the type 
of feed the site receives; see newsfeeds(5). This is useful when the site is fed 
by a file and batching is going to start. If site is an empty string, then all sites 
are flushed and the activefile and history databases are also written out. This 
command is forwarded; see below. 

Close the log and error log files and rename them to have a .old extension. 
The history database and activefile are also written out. 

Reopen the history database and start accepting articles after a pause or 
throttle command. The reason must either bean empty string or match the 
text that was given in the earlier pause or throttle command. Ifarqect 
command was done, this will also do an allow command if the reason 
matches the text that was given in the reject. If a reserve command was done, 
thiswill also clear the reservation if the reason matches the text that was given 
in the reserve Note that if only the history database has changed whilethe 
server is paused or throttled, it is not necessary to send it a reload command 
before sending it a go command. If the server throttled itself because it 
accumulated too many I/O errors, this command will reset the error count. If 
the server was not started with the -ny flag, then this command also does a 
readers command with yes astheflag and reason as the text. 

Close the socket on the specified incoming channel . Thisis useful when an 
incoming connection appears to be hung. 

Print a command summary for all commands, orjust command if specified. 
Print the server's operating mode as a multiline summary of the parameters 
and operating state. 

Print the name of channel numbernnn or of all channels if it isan empty 
string. 

Create the specified newsgroup. The rest parameter should bethefourth 
field as described in active(5); if it is not an equal sign, only the first letter is 
used. The c r eat or should be the name of the person creating the group. Ifthe 
newsgroup already exists, this is equivalent to the changegroup command. 
This isthe only command that has defaults The creator can be omitted and 
will default to the empty string, and the rest parameter can be omitted and 
will default to y. This command can be done while the server is paused or 
throttled; it will update its internal state when a go command is sent. This 
command updates the active, times (see act±ve(5)) file 
Changethecommand-line parameters of theserver. Thecombination of 
defaults makes it possible to use the text of the C ontrol header directly, 
i etter isthe innd command-line option to set, and value is the new value. 

For example, i 5 directs the server to allow only five incoming connections. 

T o enable or disable the action of the -n flag, use the letter y or n for the 

Pause the server so that no incoming articles are accepted. N o existing 
connections are closed, but the history database is closed. This command 
should be used for short-term locks, such as when replacing the history files. 

If theserver was not started with the-ny flag, then this command also does a 
readers command with no as the flag and r e a s o n as the text. 

Allow or disallow newsreaders. If f i ag starts with the letter n, then 
newsreading isdisallowed by causing the server to pass the text as the value of 
the nnrpd(8) -r flag. If f i ag starts with the letter y and text is either an empty 
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reject reason 
reload what reason 


renumber group 

reserve reason 


rmgroup group 


send feed text., 
shutdown reason 

signal si g site 

throttle reason 


trace item flag 


string, or the same string that was used when newsreading was disallowed, 
then newsreading will be allowed. 

Remote connections (those that would not be handed off to nnrpd) are 
rqected, with reason given as the explanation. 

Theserver updates its in-memory copies of various configuration files, what 
identifies what should be reloaded. If it isan empty string or the word ail, 
then everything is reloaded; if it is the word history, then the history 
database is closed and opened; if it is the word hosts.nntp, then the 
hosts .nntp(5) file is reloaded; if it is the word active or newsfeeds, then 
both the active and newsfeeds files are reloaded; if itistheword 
overview, fmt, then the overview. fmt(5) file is reloaded. T he reason is 
reported to sysiog. There is no way to reload the data inn.conf(5) file; the 
server currently only uses the pathhost parameter, so this restriction should 
not be a problem. 

Scan the spool directory for the specified newsgroup and update the low- 
water mark in the active file. If group is an empty string, then all newsgroups 
are scanned. 

The next pause or throttle command must use reason as its text. This 
reservation isdeared by giving an empty string for thereason. This 
command is used by programs such asexpire(8) thatwantto avoid running 
into other instances of each other. 

Removethespecified newsgroup. Thisisdoneby editingtheactivefile. The 
spool directory is not touched, and any articles in the group will be expired 
using the default expiration parameters. Unlike the newgroup command, this 
command does not update the active, times file. 

The specified text is sent as a control line to the exploder feed. 

Theserver isshutdown, with the specified reason recorded in the log and 
sent to all open connections. It is a good idea to send a throttle command 
first. 

Signal s i g is sent to the specified site, which must be a channel or exploder 
feed, si g can be a numeric signal number or the word hup, int, or term; case 
is not significant. 

Input is throttled so that all existing connections are closed and new 
connections are rqected. The history database is closed. This should be used 
for long-term locks, such as when expire is being run. If the server was not 
started with the -ny flag, then this command also does a readers command 
with no astheflag and reason asthetext. 

T racing is turned on or off for the specified item, flag should start with the 
letter y or n to turn tracing on or off. If i t e m starts as a number, then tracing 
is set for the specified innd channel, which must be for an incoming N NTP 
feed. If it starts with the letter i, then general innd tracing isturned on or off. 
If it starts with the letter n, then future nnrpd's will or will not have the -t 
flag enabled, as appropriate 

Theserver logs the specified reason and then invokestheabort(3) routine. 
Theserver gets ready to shut itself down, but instead of exiting, it executes 
thespecified path with all of itsoriginal arguments. If path is innd, then / 
news/bin/lnnd isinvoked; if it isinndstart, then /news/bin/inndstart is 
invoked; if it isan empty string, itwill invoke the appropriate program 
depending on whether it was started with the -p flag; any other value isan 



In addition to being acted upon within theserver, certain commands can be forwarded to the appropriate child process If 
the site receiving the command is an exploder (such asbuffchan(8)) or it is a funnel that feeds into an exploder, then the 
command can be forwarded. In this case theserver will send a command line to the exploder that consists of the ctunnd 
command name. If the site funnels into an exploder that has an asterisk (*) in its w flag (see newsfeed(5)), then the site name 
isappended to thecommand; otherwise no argument isappended. 

BUGS 

ctiinnd usesthe inndcomm(3) library and istherefore limited to server replies no larger than 4KB. 

HISTORY 

W ritten by Rich $alz (rsaizouunet. uu. net) for InterN etN ews. 

SEE ALSO 

active(5), expire(8), innd(8), inndcomm(3), inn.conf(5), newsfeeds(5), overview.fmt(5) 

ctrlaltdel 

ctnaitdei— Set the function oftheCtrUAIt-tOel combination. 

SYNOPSIS 

ctrlaltdel hard|soft 

DESCRIPTION 

Based on examination of theiinux/kernei/sys.c code, it is clear that there are two supported functionsthatthe 
CtrUAIttOel sequence can perform: a hard reset, which immediately reboots the computer without calling sync(2) and 
without any other preparation, and a soft reset, which sends the sigint (interrupt) signal to the init process (this is always 
the process with PID 1). If this option is used, theimt(8) program must support this feature. Because there are now several 
imt(8) programs in the Linux community, consult the documentation for the version that you are currently using, 
ctrlaltdel is Usually Used in the /etc/rc. local file 

FILES 

SEE ALSO 

simpleinit(8), init(8) 

AUTHOR 

PeterOrbaek (poe®daimi.aau.dk) 

Linux0.99, 25 October 1993 


cvsbug 

cvsbug— Send problem report (PR) about CVS to a central support site. 

SYNOPSIS 

cvsbug [ site ][-f probl em- repott ][-t ma i I ■ address ][-P ][-L ] 
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DESCRIPTION 

cvsbug isatool used to submit problem reports (PRs) to a central support site In most cases, the correct site will be the 
default. Thisargumentindicatesthe support site that is responsible for the category of problem involved. Some sites may use 
alocal address as a default. Site values are defined by using the aiiases(5). 

cvsbug invokes an editor on a problem report template (after trying to fill in some fields with reasonable default values). 
When you exit the editor, cvsbug sends the completed form to the Problem Report M anagement System (GNATS) at a 
central support site. At the support site, the PR is assigned a unique number and isstored in theGN ATS database according 
to its category and submitter ID. GNATS automatically replies with an acknowledgment, citing the category and the PR 
number. 

To ensure that a PR is handled promptly, it should contain your (unique) submitter ID and one of the available categories to 
identify the problem area. (U se cvsbug - l to see a list of categories.) 

The cvsbug template at your site should already be customized with your submitter ID (running install-sid submitter-id 
to accomplish this is part of the installation procedures for cvsbug). If this hasn't been done see your system administrator 
for your submitter ID, or request one from your support site by invoking cvsbug - - request-id. If your site does not 
distinguish between different user sites, or if you are not affiliated with the support site, Usenet for this field. 

The more precise your problem description and the more complete your information, the faster your support team can solve 
your problems 

OPTIONS 

-f pr obi em- report Specify a file (pr obi em- repor t ) that already contains a complete problem report, cvsbug 

sends the contents of the file without invoking the editor. If the value for pr o bi em-report 
is-, then cvsbug reads from standard input. 

-t mail-address Changemailaddressatthesupportsiteforproblem reportsThedefault ma i i-address is 

the address used forthedefault site Use the site argument rather than this option in 
nearly all cases 

-p Print the form specified by the environment variable pr form on standard output. If pr 

form is not set, print the standard blank PR template No mail issent. 

-L Print the list of available categories No mail issent. 

- - request - id Sends mai I to the default support site, or s i t e if specified, with a request for your 

submitter ID. If you are not affiliated with site, use a submitter ID of net. 

-v Display the cvsbug version number. 

Note: Use cvsbug to submit problem reports rather than mail them directly. Using both the template and cvsbug itself will 
help ensure all necessary information will reach thesupport site. 

ENVIRONMENT 

The environment variable editor specifies the editor to invoke on the template. Thedefault isvi. 

If the environment variable pr form issdt, then its value is used as the filename of the template for your problem-report 
editing session. You can use this to start with a partially completed form (for example, a form with the identification fields 
already completed). 

HOWTO FILL OUT A PROBLEM REPORT 

Problem reports have to be in a particular form so that a program can easily manage them. Please remember the following 
guidelines: 

Describeonly one problem with each problem report. 

For follow-up mail, use thesame subject line as the one in the automatic acknowledgment. It consists of category, PR 
number, and the original synopsis line This allows the support site to relate several mail messages to a particular PR and 
to record them automatically. 
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P lease try to be as accurate as possible in the subject or synopsis line. 

The subject and the synopsis line are not confidential. This is because open-bugs lists are compiled from them. Avoid 
putting confidential information there 

See the GN U Info file cvsbug. info or the document Reporting Problems With cvsbug for detailed information on reporting 
problems 

H0 W TO SU BM IT TEST CASES, CODE, AN D SO 0 N 

Submit small codesampleswith thePR. Contact the support sitefor instructionson submitting larger test cases and 
problematic source code. 

FILES 

/tmp/p$$ copy of PR used in editing session 
/tmp/pf$$ copy of empty PR form, for testing purposes 
/tmp/pbad$$fileforrqected PRs 

EMACSUSER INTERFACE 

An EM ACS user interface for cvsbug with completion of field values is part of the cvsbug distribution (invoked with m-x 
cvsbug). See the file cvsbug. info or the ASCI I file install in the top-level directory of the distribution for configuration 
and installation information. The EM ACS LISP template file is cvsbug -ei. in and is installed as cvsbug. ei. 

INSTALLATION AND CONFIGURATION 

See cvsbug.info or IN sTALL for installation instructions 

SEE ALSO 

Reporting ProblemsU sng cvsbug (also installed astheGN U Info file cvsbug.info). 
gnats(l), query-pr(l), edit-pr(l), gnats(8), queue-pr(8), at-pr(8), mkcat(8), mkdist(8) 

AUTHORS 

Jeffrey Osier, Brendan Kehoejason Merrill, HeinzG. Seidl (Cygnus Support). 

COPYING 

Copyright(c) 1992,1993 Free Software Foundation, Inc. Permission isgranted to make and distribute verbatim copiesof 
this manual provided the copyright notice and this permission notice are preserved on all copies 
Permission isgranted to copy and distribute modified versions of this manual under the conditionsfor verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to thisone. 
Permission isgranted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in theoriginal English. 

xVERSiONx, February 1993 


cvtbatch 

cvtbatch—Convert Usenet batch file to IN N format. 

SYNOPSIS 


cvtbatch [ -w i i 
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DESCRIPTION 

cvtbatch reads standard input as a series of lines, converts each line, and writes it to standard output. It is used to convert 
si mplebatchfiles that contain just the article name to IN N batchfiles that contain additional information about each article 
Each line is taken as the pathname to a Usenet article. If it is not an absolute pathname, it istaken relative to the spool 
directory, / news/spool. (0 nly the first word of each line is parsed; anything following whitespace is ignored.) 

T he-w flag specifies how each output line should be written. The items for this flag should be chosen from the w flag items 
as specified in newsfeeds(5). They may be chosen from the following set: 
b Size of article in bytes 

t Full pathname of article 

m Article Message-1 D 

n Relative pathname of article 

If the input file consists of a series of M essage- IDs, then usegrephistory(l) with the-s flag piped into cvtbatch. 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet. uu. net) for InterN etN ews. 

SEE ALSO 

grephistory(l) newsfeeds(5) 

cytune 

cytune—TuneCydades driver parameters. 

SYNOPSIS 

cytune [-q [-1 interval ]] ([-s value]|[-S value]) 

[-g|G] ([-t ti meout ]■[-T timeout ]) tty [tty ...] 

DESCRIPTION 

cytune queries and modifies the interruption threshold for theCyclades driver. Each serial line on a Cyclades card has a 12- 
byte FIFO for input (and another 12-byte FIFO for output). The "threshold" specifies how many input characters must be 
presentin the FIFO before an interruption israised. When aCydadestty isopened, thisthreshold issetto a default value 
based on baud rate 

Baud Thrediold 

50-4800 10 

9600 8 

19200 4 

38400 2 

57600-150000 1 

If the threshold issettoo low, the large number of interruptions can load the machine and decrease overall system through¬ 
put. If the threshold issettoo high, the FIFO buffer can overflow, and characters will be lost. Slower machines, however, 
may not be able to deal with the interrupt load and will require that thethreshold be adjusted upwards 
If the Cyclades driver was compiled with enable monitoring defined, the cytune command can be used with the -q option 
to report interrupts over the monitoring interval and characters transferred over the monitoring interval. It will also report 
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the state of the FI FO. The maximum number of characters in the FI FO when an interrupt occurred, the instantaneous 
count of characters in the FIFO, and how many characters are now in the FIFO are reported. This output might look like 
this: 

/dev/cubC0: 830 ints, 9130 chars; fifo: 11 threshold, 11 max, 11 now 
166.259866 interrupts/second, 1828.858521 characters/second 

Thisoutput indicates that for this monitoring period, the interrupts were always being handled within onecharactertime 

because max never rose above threshold. T his is good, and you can probably run this way, provided that a large number of 

samples come out this way. You will lose characters if you overrun the FIFO because the Cyclades hardware does not seem to 

support the RTS RS-232 signal line for hardware flow control from the DC E to the DTE. 

cytune will in query mode produce a summary report when ended with asiGiNTorwhen the threshold or time-out is 

changed. 

There may be a responsiveness versus throughput tradeoff. TheCydades card, at the higher speeds, iscapableof putting a 
very high interrupt load on the system. This will reduce the amount of CPU time avai lablefor other tasks on your system. 
Flowever, the time it takes to respond to a single character may be increased if you increase the threshold. This might be 
noticed by monitoring p±ng(8) times on a SLIP link controlled by a Cyclades card. If your SLIP link is generally used for 
interactive work such asteinet(l), you might want to leave the threshold low so that characters are responded to as quickly 
as possible. If your SLIP link is generally used for file transfer, WWW, and the like setting the FIFO to a high value is likely 
to reduce the load on your system while not significantly affecting throughput. Alternatively, see the -t or -t optionsto 
adjust the time that the Cyclades waits before flushing its buffer. U nits are 5ms 

If you are running a mouse on a Cyclades port, it is likely that you want to maintain thethreshold and time-out at a low 
value. 

OPTIONS 

-s value Set the current threshold to value characters Note that if the tty is not being held open 

by another process thethreshold will be reset on the next open. 0 nly values between i 
and 12, inclusive are permitted. 

-t value Setthecurrentflushtime-outtovaiue units Note that if the tty is not being held open 

by another process thethreshold will be reset on the next open. 0 nly values between 0 
and 255, inclusive, are permitted. Setting value to ©forces thedefault, currently 0x20 
(160ms) but soon to be 0x02 (10ms). U nits are 5ms. 

-g Get the current threshold and time-out. 

-t value Set the default flush time-out to value units When the tty is next opened, this value is 

used instead of the default. If value iso, then the value defaults to 0x20 (160ms), soon to 
be 0x02 (10ms). 

-g Get the default threshold and flush time-out values. 

-q Gather statistics about the tty. The results are only valid if the Cyclades driver has been 

compiled with enable monitoring defined. Thisisprobably not thedefault. 

-i interval Statistics will be gathered every i nt er va 1 seconds. 

BUGS 

If you run two copies of cytune at the same time to report statistics about the same port, the ints, chars, and max values will 
be reset and not reported correctly. cytune(8) should prevent this but does not. 

AUTHOR 

N ick Simicich (njs@sdfi.emi.net), with modifications by Rik Faith (faith@cs.unc.edu) 
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FILES 

/dev/ttyC[0-8] 

/dev/cubC[0-8] 

SEE ALSO 

setserial(8) 


4 M arch 1995 


debugfs 

debugfs— ext2 filesystem debugger. 

SYNOPSIS 

debugfs [[-w ]devi ce] 

DESCRIPTION 

debugfs is a filesystem debugger. It can be used to examine and change the state of an ext2 filesystem, device isthe special 
fi le correspondi ng to the device containing the ext2 fi lesystem (such as / dev / hdxx). 

OPTIONS 

-w Specify that the filesystem should beopen in read-write mode Without this option, 

the filesystem isopen in read-only mode. 


COMMANDS 

debugfs isan interactive debugger. It understands a number of commands 


cd file 
chroot file 

expand_dir, file 
find_free_block [goal ] 
find_free_inode [dir [mode]] 
freeb bl ock 
freei file 
help 

Initialize device blocksize 
id ll_f.il e file 
In s o u r c e _ f i I e d e s t _ f i I e 
Is [pathname] 

Modify_inode file 

open [-w] d ev i ce 


Close the currently open filesystem. 

Clear thecontents of theinode corresponding to f i i e. 

Expand a directory. 

Find the first free block, starting from goal , and allocate it. 

Find a free inode and allocate it. 

M ark the block as not allocated. 

Free the inode corresponding to f i i e. 

Print the filename corresponding toi node (currently not implemented). 
Create an ext2 file system ondevi ce. 

Remove a file and deallocate its blocks 
Create a link. 

Emulate the is(l) command. 

M odify the contents of theinode corresponding to f i i e. 

Make a directory. 

Open a filesystem. 


Quit debugfs. 
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setb bl ock 


show_super_stats 

testb bl ock 


unlink file 


Remove a file. 

Remove a directory. 

M ark the block as allocated. 

M ark in usetheinodecorresponding to file 
Listthe contents of the super block. 

Dump the contents of the inode corresponding to fi i e. 

Test if the block is marked as allocated. 

Test if the inode corresponding to f i i e is marked as allocated. 
Remove a link. 


AUTHOR 

debugfs was written by Theodore T'so (tytso@mit.edu). 

SEE ALSO 

dumpe2f s(8), e2fsck(8), mke2f s(8) 

Verson 0.5b, N ovemberl994 


dip 

dip— D ialup IP connection handler. 

SYNOPSIS 

dip [t] 

dip [-ktv] [ -m mtu ] scri ptfiI e 
dip [-iv] [u s e r _ n a me ] 

DESCRIPTION 

dip handles the connections needed for dialup IP links, such as SLIP or PPP. It can handle both incoming and outgoing 
connections, using password security for incoming connections The outgoing connections use the system's diai{3) library 
if available. 

COMMAND MODE 

The first possible use of dip isasa stand-alone program to set up an outgoing IP connection. Thiscan be done by invoking 
dip with the -1 option, which means enter test mode and, more precisely, dump you in the command-mode of the dip 
program. You are reminded ofthisbytheDip> prompt, or, if you also specified the -v debugging flag, theDip [nnnn]> 
prompt. The latter prompt also displaysthe current value of the global errivi variable which is used mostly when dip runs 
in script mode. For the interactive mode it can be used to determine if the result of the previous command was okay. 
Thefollowingisasampletaken from a live session: 

$dip-t 

DIP: Dialup IP Protocol Driver version 3.3.7 (12/13/93) 

Written by Fred N. van Kempen, MicroWalt Corporation. 


DIP>_ 

The most helpful command in this mode is, of course, the help command, which should produce an output similar to this: 

DIP> help 

DIP knows about the following commands: 
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databits default dial echo flush 
get goto help if init 
mode modem parity print port 
reset send sleep speed stopbits 


DIP>_ 

All commands display how they should be used when invoking them with no or invalid arguments Just experiment a little to 
get the feel of it, and have a look at the sample script files, which also use this command language. 

DIALIN MODE 

Thesecond possibleway of using dip isasa login shell for incoming IP connections asin dialup SLIP and PPP connections. 
To make integration into theexisting UNIX system as easy as possible, dip can be installed as simply as using it asa login 
shell in the system's password file. A sample entry looks like 

suunet:ij/SMxiTIGVCo:1004:10:UUNET:/trap:/usr/bin/dip -i 

When user suunet logs in, the iogin(l) program sets the home directory to /tmp and execute the dip program with the -i 
option, which means that dip must run in input mode dip then triesto locate the name of the logged-in user (the name 
corresponding to its current user ID, as returned by thegetuid(2) system call) in its database file An optional single 
argument to the dip program in this mode can be the username that must be used in this lookup, regardless of the current 
user ID. 

dip now scans the /etc/net/diphostsfileforan entry for the given username Thisfile contains lines of text (much like the 
standard password file). Theformat lookslike 

# diphosts This file describes a number of name to 

# address mappings for the DIP program. It 

# is used to determine which IP address to 

# use for in incoming call of some user. 

# Version: @(#)diphosts 1.00 12/10/92 FvK 

# Author: Fred N. van Kempen, 

# <waltje@uwalt.nl.mugnet.org> 

suunet::uunet.uu.net:UUNET SLIP:SLIP,296 

# End of diphosts. 

Thefirst field of a line identifies the username, which you must match. Thesecond field can contain an encrypted password. 
If thisfield is non-null, the dip program asks for an external security password, which must match the password in this field. 
The third field contains the name (or raw IP address) of the host that is connecting to the system with this link. If a 
hostname is given, the usual address resolving process is started, using either a nameserver or a local hosts file. 

Thefourth field can contain any text; it is not (yet) used by the dip program. In future releases this info may be used in the 
system log files Finally, thefifth field of a line containsamixtureof comma-separated flags. Possible flags are 
slip to indicate you must use the SLIP protocol. 
ppp to indicate you must use the PPP protocol, 
number .which gives the MTU parameter of this connection. 

After finding the correct line, dip puts the terminal line into RAW mode and asks the system networking layer to allocate a 
channel of the desired protocol. Finally, if the channel is activated, it adds an entry to the system's routing table to make the 
connection work. 
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dip now goes into an endless loop of sleeping, which continues until the connection is physically aborted (the line is 
dropped). At that time, dip removes the entry it made in the system's routing table and releases the protocol channel for 
reuse. It then exits, making room for another session. 

DIALOUTMODE 

The last way of using dip is as a program that initiates outgoing connections T o make life easier for the people who have to 
manage links of this type, dip uses a chat script to set up a link to a remote system. This gives the user an enormous amount 
of flexibility when making the connection, which otherwise could require many command-line options The pathname of 
thescript to be run isthen given as thesingle argument to dip; the program will automatically check if thefilehasa filename 
ending in a .dip part. This is not mandatory-just a tool to group scripts together in a single directory. A script should look 
something like this: 

# sample.dip Dialup IP connection support program. 

# This file (should show) shows how to use the DIP 

# scripting commands to establish a link to a host. 

# This host runs the 386bsd operating system, and 

# thus can only be used for the "static" addresses. 

# 

# NOTE: We also need an examnple of a script used to 

# connect to a "dynamic" SLIP server, like an Annex 

# terminal server... 

# Version: @(#)sample.dip 1.30 07/05/93 

# Author: Fred N. van Kempen, <waltje@uWalt.NL.Mugnet.ORG> 


# First of all, set up our name for this connection. 

# I am called "uwalt.hacktic.nl" (== 193.78.33.238) 
get $local uwalt.hacktic.nl 

# Next, set up the other side's name and address. 

# My dialin machine is called 'xs4all.hacktic.nl' (== 193.78.33.42) 
get Sremote xs4all.hacktic.nl 

# Set the desired serial port and speed, 
port cua0 

speed 38400 

# Reset the modem and terminal line. 

# This seems to cause trouble for some people! 

# Prepare for dialing, 
send ATQ0V1E1X1 

wait OK 2 

if Serrlvl != 0 goto error 
dial 555-1234567 
if Serrlvl != 0 goto error 
wait CONNECT 60 
if Serrlvl != 0 goto error 

# We are connected. Login to the system. 

send \r\n\r\n 
wait ogin: 10 

if Serrlvl != 0 goto error 
send N0-WAY\n 
wait ord: 5 

if Serrlvl != 0 goto error 
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send sliplogin\n 
wait SOME-STRING 15 

# Set up the SLIP operating parameters, 
get $mtu 1500 

# Set Destination net/address as type 'default' (vice an address). 

# This is used by the 'route' command to set the kernel routing table. 

# Some machines seem to require this be done for SLIP to work properly, 
default 

# Say hello and fire up! 


print CONNECTED to $remote with address Srmtip 
mode SLIP 
goto exit 


print SLIP to Sremote failed. 

This script causes dip to dial up a host, login, and get a SLIP interface channel going (in the same manner as with incoming 
connections). When all is set up, it simply goes into the background and waits for a hangup (or just a lethal signal), at which 
it hangs up and exits. 

FILES 

/etc/passwd 

/etc/diphosts 

AUTHORS 

Fred N . van Kempen (waltje@uwalt.nl.mugnet.org), Paul M Ossip (mossip@vizlab.rutgers.edu), Jeff Uphoff 
(juphoff@aoc.nrao.edu), Jim Seagrave(jes@grendel.demon.co.uk), Olaf Kirch (okir@monad.sub.de). 

Verson 3.3.7,13 D ecember 1993 


dmesg 

dmesg— Print or control the kernel ring buffer. 

SYNOPSIS 

dmesg [ -c ] [ -n I evel ] 

DESCRIPTION 

dmesg isused to examine or control the kernel ring buffer. 

The program helps users to print their bootup messages Instead of copying the messages by hand, the user need only 

dmesg > boot .messages 

and mail the boot, messages file to whoever can debug their problem. 
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OPTIONS 

-c Clear the ring buffer contents after printing. 

-n level Sdt the I evel at which logging of messagesisdoneto theconsole For example -n i 

prevents all messages, except panic messages, from appearing on theconsole All 
level s of messages are sti 11 written to /proc/kmsg, so sysiogd(8) can still be used to 
control exactly where kernel messages appear. When the-n option is used, dmesg 
will not print or clear the kernel ring buffer. 

When both options are used, only the last option on the command line will have an effect. 

SEE ALSO 

syslogd(8) 

AUTHOR 

TheodoreTs'o (tytso@athena.mit.edu) 

Linux0.99, 28 October 1993 


dumpe2fs 

dumpe 2 ts— D ump filesystem information. 

SYNOPSIS 

dumpe2fs dev i ce 

DESCRIPTION 

dumpe 2 t s prints the super block and blocks group information for the filesystem present on device. 
dumpe 2 ts issimilar to Berkeley's dumpts program for the BSD Fast FileSystem. 

BUGS 

You need to know the physical filesystem structure to understand the output. 

AUTHOR 

dumpe 2 t s was written by Remy Card (card@masi.ibp.fr), the developer and maintainer of theext 2 fs. 

AVAILABILITY 

dumpe 2 fs is available for anonymous FTP from ftp.ibp.fr and tsx -11 .mit.edu in /pub/linux/packages/ext 2 fs. 

SEE ALSO 

e2fsck(8), mke2fs(8), tune2fs(8) 

Verson 0.5b, N ovember 1994 


e2fsck 

e 2 fsck— C heck a Linux second extended filesystem. 

SYNOPSIS 

e2fsck [ -panyrdfvtFV ][-b superblock ][-B blocksize ] 
[-1!-L b ad_ bI ocks _fiI e ] device 
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DESCRIPTION 

e2fsck is used to check a Linux second extended filesystem. 

devi ce The special file corresponding to the device (such as/dev/hdxx). 


OPTIONS 



This option does the same thing as the -p option. It is provided for backwards 
compatibility only; it is suggested that people use -p option whenever possible. 
Instead of using the normal superblock, use the alternative superblock specified by 

super bl ock. 

Usually, e2tsck will search for the superblock at various different block sizes in an 
attempt to find the appropriate block size. This search can befooled in some cases 
This option forces e2fsck to only try locating the superblock at a particular 
bi ocksi ze. If the superblock is not found, e2fsckwill terminate with afatal error. 
Print debugging output (useless unless you are debugging e2tsck). 

Force checking even if the filesystem seemsdean. 

Flush thefilesystem device's buffer caches before beginning. Only really useful for 
doing e2fsck time trials 

Add the blocks listed in the file specified by filename to the list of bad blocks. 

Sbt the bad blocks list to be the list of blocks specified by f i i ename. (This option is 
the same as the -1 option except the bad blocks list is cleared before the blocks listed 
in thefile are added to the bad blocks list.) 

Open thefilesystem read-only, and assume an answer of "no" to all questions. 

Allows e2f sek to be used non-interacti vely. (N ote: if the -1 or - l options are 
specified in addition to the -n option, then thefilesystem will be opened read-write 
to permit the bad-blocks list to be updated. Flowever, no other changes will be made 
to thefilesystem.) 

Automatically repair ("preen") thefilesystem without any questions. 

Thisoption does nothing at all; it is provided only for backwardscompatibility. 

Print timing statistics for e2fsck. If thisoption isused twice additional timing 
statistics are printed on a pass-by-pass basis 
Verbose mode. 

Print version information and exit. 

Assume an answer of "yes" to all questions; allows e2f sek to be used non- 
interacti vely. 


EXIT CODE 

The exit code returned by e2fsck isthesum of thefollowing conditions: 


0 No errors 

1 Fi lesystem errors corrected 

2 Filesystem errors corrected; system should be rebooted if filesystem was mounted 

4 Fi lesystem errors left uncorrected 

8 Operational error 

U sage or syntax error 
Shared library error 


16 

128 
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BUGS 

Almost any piece of software will have bugs If you manage to find a filesystem that causes e2fsck to crash, or that e2fsck is 
unable to repair, please report it to the author. 

Please include as much information as possible in your bug report. Ideally, include a complete transcript of the e2tsck run, 
so I can see exactly what error messages are displayed. If you have a writeable filesystem where the transcript can be stored, 
the script(l) program isa handy way to save the output of e2fsck to a file 

It is also useful to send the output of dumpe2fs(8). If a specific inode or inodes seems to be giving e2fsck trouble, try 
running the debugfs(8) command and send the output of the stat command run on the relevant inodes. If the inode is a 
directory, thedebugfs dump command will allow you to extract the contents of the directory inode which can sent to me 
after being first run through uuencode(l). 

Always include the full version string that e2fsck displays when it is run so I know which version you are running. 

AUTHOR 

This version of e2fsck is written by Theodore Ts'o (tytso@mit.edu). 

SEE ALSO 

mke2f s(8), tune2fs(8), dumpe2fs(8), debugfs(8) 

Veraon 0.5b, N ovemberl994 


edquota 

edquota— Edit user quotas 

SYNOPSIS 

/usr/etc/edquota [ -p proto-user ][-ug ] name... 

/usr/etc/edquota [ -ug ] -t 

DESCRIPTION 

edquota is a quota editor. 0 neor more users or groups may be specified on the command line. For each user or group, a 
temporary file is created with an ASCII representation of the current disk quotas for that user or group and an editor isthen 
invoked on the file The quotas may then be modified, new quotas added, and so on. Upon leaving theeditor, edquota reads 
the temporary file and modifies the binary quota files to reflect the changes made 
Theeditor invoked is vi(l) unless the environment variable specifies otherwise. 

Only the superuser may edit quotas. (For quotas to be established on afilesystem, the root directory of the filesystem must 
contain a file owned by root, called quota, user or quota, group. Seequotaon(8) for details) 

OPTIONS 

-u Edit the userquota. This is the default. 

-g Edit the groupquota. 

-p Duplicate the quotas of the prototypical user specified for each user specified. This is 

the normal mechanism used to initialize quotas for groups of users 
-t Edit thesoft time limitsfor each filesystem. If the time limitsare zero, thedefault 

time limits in <iinux/quota. h> are used. Time units of sec(onds), min(utes), 
hour(s), day(s), week(s), and month(s) are understood. Time limits are printed in the 
greatest possible time unit such that the value is greater than or equal to one 
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FILES 

quota, user or quota, group Q uota file at the filesystem root 

/etc/mtab M ounted filesystems 

SEE ALSO 

quota(l), vi(l), quotactl(2), quotacheck(8), quotaon(8), repquota(8) 

BUGS 

The format of the temporary file is inscrutable. 

8Junel993 


expire 

expire— U senet article and history expiration program. 

SYNOPSIS 

expire [ -d di r ] [ -f file ] [ -g file ] [-h file ] 
l-i ][-1 11-n ][-p ][-q ][-r reason |[-s ] [ -t ] 

[-V level ][-w number ][-x ][-z file ][expire.ctl] 

DESCRIPTION 

expire scansthehistory(5) text file /news/iib/history and uses the information recorded in it to purge old news articles 
To specify an alternate history file, use the-f flag. To specify an alternate input text history file, use the-h flag, expire uses 
the old dbz(3z) database to determine the size of the new one To ignore the old database, use the-i flag, 
expire usually just unlinks each file if it should be expired. If the -1 flag is used, then all articles after thefirst one are treated 
as if they could be symbolic links to thefirst one. In this case, the first article will not be removed as long as any other cross- 
posts of the article remain. 

expire usually sends a pause command to the local innd(8) daemon when it needs exclusive access to the history file using 
the string Expiring as the reason. To give a different reason, usethe-rflag. The process ID will be appended to the reason. 
When expire isfinished and the new history file is ready, it sends a go command. If innd is not running, usethe-nflag and 
expire will not send the pause or go commands. (For more details on the commands, see ctiinnd(8).) Note that expire 
only needs exclusive access for a very short time— long enough to see if any new articles arrived since it first hit the end of the 
fileand to renamethenew files to the working files. 

If the -s flag is used, then expire will print a summary when it exits, showing the approximate number of kilobytes used by 
all deleted articles. 

If the-t flag is used, then expire will generate a list of the files that should be removed on its standard output, and the new 
history file will be left in history, n, history, n. dir, and history, n.pag. Thisflag is useful for debugging when used with 
the-n and -s flags N ote that if the -f flag is used, then the name specified with that flag will be used instead of history. 

If the-x flag is used, then expire will not create any new history files This is most useful when combined with the-n, -s, 
and -t flags to see how different expiration policies would change the amount of disk space used. 

If the-z flag is used, then articles are not removed, but their names are written to the specified file. See the description of 
expirermin news. daily(8). 

expire makes its decisions on the time the article arrived, as found in the history file. This means articles are often kept a 
little longer than with other expiration programs that base their decisions on the article's posting date To use the article's 
posting date, use the-p flag. Usethe-wflagto "warp" time so that expire thinks it is running at some time other then the 
current time. T he value should be a signed floating-point number of the number of days to use as the offset. 



expireover 


If the -d flag is used, then the new history file and database is created in the specified directory, dir. This is useful when the 
filesystem does not have sufficient space to hold both the old and new history files. When thisflag is used, expire leaves the 
server paused and creates a zero-length file named after the new history file, with an extension of .done to indicate that it has 
successfully completed the expiration. The calling script should install the new history file and unpause the server. The-r 
flag should be used with thisflag. 

If a filename is specified, it istaken as the control file and parsed according to the rules in expire. cti(5). A single dash (-) 
may be used to read the file from standard input. If no file is specified, thefile /news/iib/expire.ctiisread. 
expire usually complains about articles that are posted to newsgroups not mentioned in the active file. T o suppress this 
action, use the -q flag. 

T he-v flag is used to increase the verbosity of the program, generating messages to standard output. The level should be a 
number, where higher numbers result in moreoutput. Level one will print totals of the various actions done (not valid if a 
new history file is not written), level two will print report on each individual file and level five results in more than one line 
of output for every line processed. If the -g flag isgiven, then a one-line summary equivalent to the output of -vi and 
preceded bythecurrenttimewill be appended to the specified file. 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet. uu. net) for InterN dtN ews. 

SEE ALSO 

ctlinnd(8), dbz(3z), expire.ctl(5), history(5), innd(8), inndcomm(3) 

expireover 

expireover—Expire entries from the news overview database 

SYNOPSIS 

expireover [ -a ][-D overvi ewdi r ][-f file ][ -n ] 

[-0 overvi ew. f mt ] [ -s ][ -v ][ -z ] [f i I e ... ] 


DESCRIPTION 

expireover expires entries from the news overview database It reads a list of pathnames (relative to the spool directory, / 
news/spool) from the specified files or standard input if none are specified. (A filename of - may be used to specify the 
standard input.) It then removes any mention of those articles from the appropriate overview database If the-z flag is used, 
then the input is assumed to be sorted such that all entries for a newsgroup appear together so that it can be purged at once 
Thisflag can be useful when used with the sorted output of expire(8)'s-zflag. 

If the-s flag is used, then expireover will read the spool directory for all groups mentioned in theactive(5) file and 
remove the overview entries for any articles that do not appear. To specify an alternate file use the-f flag; a name of - is 
taken to mean the standard input. 

The-a flag reads the spool directory and adds any missing overview entries. It will create files if necessary. This can be used 
to initialize a database or to sync up a overview database that may be lacking articles due to a crash, overchan should be 
running, to ensure that any incoming artidesget included. Using thisflag implies the-s flag; the-f flag may be used to add 
only a subset of the newsgroups. 

To see a list of the entries that would be added or deleted, use the-v flag. To perform no real updates, usethe-nflag. 

The -d flag can be used to specify where the databases are stored. The default directory is /news/spool. 

T he-o flag may be used to specify an alternate location for the overview.fmt(5) file; this is usually only useful for debug¬ 
ging. 
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HISTORY 

Written by Rob Robertson (rob@vioiet.berkeiey.edu) and Rich $alz (rsaiz@uunet.uu.net) with help from Dave 
Laurence (taie@uunet. uu. net) for InterN etN ews. 

SEE ALSO 

expire(8), overview.fmt(5) 

fastrm 

f ast ™— Q uickly remove a set of fi les. 

SYNOPSIS 

fast™ [ -d ] [-e ] [ -uN ] [ - sM ][^§rj b a s e_ d i rectory 

DESCRIPTION 

f ast™ readsa list of files, one per line from its standard input and removes them. If a file is not an absolute pathname it is 
taken relative to the directory specified on the command line. The base directory parameter must be a simple absolute 
pathname— that is, it must not contain any /. / or /.. / references 

fastrm isdesigned to be faster than the typical | xargs ™ pipeline For example, fastrm will usually chdir(2) into a 
directory before removing files from it. If theinput is sorted, thismeansthat most files to be removed will be simple names, 
fastrm assumes that its input is valid and that it issafe to just do an umink(2) call for each item to be removed. As a safety 
measure, if fastrm is run by root, it will first stat(2) the item to make sure that it is not a directory before unlinking it. 

If the-d flag is used, then no files are removed. Instead, a list of the files to be removed, in debug form, is printed on the 
standard output. Each line contains either the current directory of fast™ at the time it would do the unlink and then the 
pathname it would pass to umink(2) as two fields separated by white space and a / or the absolute pathname (a single field) 
of files it would unlink using the absolute pathname. 

If the-e flag is used, fast™ will treat an empty input file (stdin) as an error. This is most useful when fast™ islast in a 
pipeline after a preceding sort(l) because if the sort fails, there will usually be no output to become input of fast™. 

If the-u flag is used, then fast™ makes further assumptions about its work environment—in particular, that there are no 
symbolic links in the target tree. Thisflag also suggests that it is probably faster to reference the path rather than 

start from the root and comedown (note that this probably isn't true on systems that have a namei cache which usually 
holds everything except..). The optional n is an integer that specifies the maxi mum number of.. segments to use- paths 
that would use more than this use the absolute pathname (from the root) instead. If the-u flag is given without a value -ui 
is assumed. 

If the-s flag is used, then fast™ will perform the unlinks from one directory—that is, when a group of files in one 
directory appear in theinput consecutively—in the order that the files appear in the directory from which they are to be 
removed. The intent of thisflag isthat on systems that have a per-process directory cache, finding files in the directory 
should be faster. It can have smaller benefits on other systems T he optional m is an integer that specifies the number of files 
that must be going to be removed from one directory before the files will be ordered. If the-s flag is given withouta value 
-s5 isassumed. W hen the directory reordering is in use, fast™ will avoid attempting to unlink files that it can't see in the 
directory, which can speed it appreciably when many of the filenames have already been removed. 

T he-c flag may be given to instruct fast™ when it should chdir(2). If the number of files to be unlinked from a directory 
isat least i, then fast™ will chdir and unlink the files from in thedirectory. Otherwise, it will build a path relative to its 
current directory. If -c isgiven without the optional integer i,then -ci isassumed, which will cause fast™ to always use 
chair. If -c is not used at all, then -c3 isassumed. Use-co to prevent fastrm from ever using chdir(2). 
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There are also -a and -r options, which do nothing at all except allow you to say tastrm -usa, fast™ -ussr, or fast™ 
-user. These happen to often be convenient sets of options to use. 

fast™ exits with a statusof 0 if there were no problemsor 1 if something went wrong. Attempting to remove a file that does 
not exist is not considered a problem. If the program exits with a nonzero status, it is probably a good idea to feed the list of 
filesintoan xargs rm pipeline. 

fdformat 

fdformat— Low-level formats a floppy disk. 

SYNOPSIS 

fdformat [ -n ] device 

DESCRIPTION 

fdformat does a low-level format on a floppy disk, device is usually one of the following (for floppy devices, the major is 2, 
and the minor is shown for informational purposes only): 

/dev/fd0d360 (minor =4) 

/dev/fd0hi200 (minor =8) 

/dev/fd0D360 (minor =12) 

/dev/fd0H360 (minor =12) 

/dev/fd0D720 (minor =16) 

/dev/fd@H720 (minor =16) 

/dev/fd@h360 (minor =20) 

/dev/fd@h720 (minor =24) 

/dev/fd0Hi440 (minor =28) 

/dev/fdi d360 (minor =5) 

/dev/fdi hi200 (minor =9) 

/dev/fdi D360 (minor =13) 

/dev/fdi H360 (minor =13) 

/dev/fdiD720 (minor =17) 

/dev/fdiH720 (minor =17) 

/dev/fdi h360 (minor =21) 

/dev/fdi h720 (minor =25) 

/dev/fdiHi440 (minor =29) 

Thegeneric floppy devices, /dev/fdo and /dev/fdi, will fail to work with fdformat when a non-standard format is being 
used or if the format has not been autodetected earlier. In this case, usesetfdprm(8) to load the disk parameters 

OPTIONS 

-n No verify. This option will disable the verification that is performed after the format. 

SEE ALSO 

fd(4), setfdprm(8), mkfs(8), emkfs(8) 
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AUTHOR 

W erner Almesberger (almesberianessie. cs. id. ethz. ch) 


Linux 0.99,1 February 1993 


fdisk 

fdisk— Partition table manipulator for Linux. 

SYNOPSIS 

fdisk [ -1 ] [ -V ] [ -s partition] [ device ] 

DESCRIPTION 

fdisk is a menu-driven program for manipulation of the hard disk partition table T hedevice is usually one of thefollowing: 

/dev/hda 

/dev/hdb 

/dev/sda 

/dev/sdb 

The partition isa de/ice name followed by a partition number. For example /dev/hdai isthefirst partition on thefirst hard 
disk in the system. 

If possible, fdisk will obtain the disk geometry automatically. This is not necessarily the physical disk geometry but is the 
disk geometry that MS-DOS uses for the partition table If fdisk warns you that you need to set the disk geometry, please 
believethisstatementand set the geometry. Thisshould only be necessary with certain SCSI host adapters (the drivers for 
which are rapidly being modified to provide geometry information automatically). 

Whenever a partition table is printed, a consistency check is performed on the partition table entries This check verifies that 
the physical and logical start and end points are identical and that the partition starts and ends on a cylinder boundary 
(except for the first partition). 

Old versions of fdisk (all versions prior to l.lr including 0.93) incorrectly mapped thecyiinder/head/sector specification 
onto absolute sectors. This might result in thefirst partition on a drive failing the consistency check. If you useLILO to 
boot, this situation can be ignored. However, there are reports that the OS/2 boot manager will not boot a partition with 
inconsistent data. 

Some versions of M S-D OS create a first partition that does not begin on a cylinder boundary but on sector 2 of thefirst 
cylinder. Partitions beginning in cylinder 1 cannot begin on a cylinder boundary, but this is unlikely to cause difficulty 
unless you have OS/2 on your machine. 

In version l.lr, aBLKRRPART ioctio is performed before exiting when the partition table is updated. Thisis primarily to 
ensure that removable SC SI disks have their partition table information updated. If the kernel does not update its partition 
table information, fdisk warnsyou to reboot. If you do not reboot your system after receiving such a warning, you might 
loseor corrupt the data on thedisk. Sometimes blkrrpart fails silently; when installing Linux, you should always reboot 
after editing the partition table 

DOS 6JY WARNING 

TheDOS 6.x format command looksfor some information in thefirst sector of the data area of the partition and treats this 
information as more reliable than the information in the partition table, dos format expects DOS fdisk to clear thefirst 
512 bytes of the data area of a partition whenever a size change occurs, dos format will look at this extra information even if 
the /u flag isgiven 
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WeconsiderthisabuginDOs format and dos fdisk. 

The bottom line isthat if you use cfdisk or fdisk to change the size of a DOS partition table entry, then you must also use 
dd to zero thefirst 512 bytes of that partition before using dos format to format the partition. For example if you were 
using cfdisk to make a D 0 S partition table entry for /dev/hdai, then (after exiting fdisk or cfdisk and rebooting Linux 
so that the partition table information is valid) you would usethecommand dd if=/dev/zero of=/dev/hdai bs=5i2 
count=i to zero thefirst 512 bytes of the partition. 

Be extremely careful if you use the dd command because a small typo can make all of the data on your disk useless 
For best results you should always use an OS-specific partition table program. For example, you should make DOS 
partitions with the dos fdisk program and Linux partitions with the Linux fdisk or Linux cfdisk program. 

OPTIONS 


BUGS 

Although this man page (written byfaith@cs.unc.edu) is poor, there is excellent documentation in the readme, fdisk file 
(written by LeBianc@mcc.ac.uk) that should always be with the fdisk distribution. If you cannot find this file in theutii- 
unux-* directory or with the f disk, c source file then you should write to the distributor of your version of fdisk and 
complain that you do not have all of the available documentation. 

AUTHOR 

A.V. LeBlanc (LeBianc@mcc.ac.uk). vl.Or: SCSI and extfs support added by Rik Faith (faith@cs.unc.edu). vl.lr: Bug 
fixes and enhancements by Rik Faith (faith@cs.unc.edu), with special thanks to M ichael Bischoff (n041905@ws.rz. tu¬ 
bs. de or mbi@mo.math.nat.tu-bs.de). vl.3: Latest enhancements and bug fixes by A.V. LeBlanc, including theaddition 
of the -soption. v2.0: Disks larger than 2GB are now fully supported, thanksto Remy Card's liseek support. 

Linux 1.0,3 Junel995 


Prints version number of fdisk program. 

Lists the partition tables for /dev/hda, /dev/hdb, /dev/sda, /dev/sdb, /dev/sdc, / 
dev/sdd, /dev/sde, /dev/sdf, /dev/sdg, and /dev/sdh and then exits. 

If the parti ti on is not a D 0 S partition (the partition ID is greater than 10), then the 
size of that partition is printed on the standard output. This value is usually used as 
an argument to the mkf s(8) program to specify the size of the partition that will be 
formatted. 


filechan 

filechan— File-writing back end for InterN dtN ews 

SYNOPSIS 

filechan [ -d directory ][-f f i el ds ][ -m mapf i I e ][-p pi df i I e ] 

DESCRIPTION 

filechan reads lines from standard input and copies certain fields in each line into files named by other fields within the 
line filechan isintended to be called by innd(8) asa channel feed. (It is not a full exploder and does not accept commands; 
see newsf eeds(5) for a description of the difference and buffchan(8) for an exploder program.) 
filechan input is interpreted as a set of lines. Each line contains a fixed number of initial fields, followed by a variable 
number of filename fields All fields in a line are separated by whitespace The default number of initial fields is one the-f 
flag may be used to specify a different number of fields 
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For each line of input, fiiechan writes the initial fields, separated by whitespace and followed by a newline to each of the 
files named in the filename fields When writing to a file, fiiechan opens it in append mode and tries to lock it and change 
the ownership to the user and group who owns the directory where the file is being written. 

By default, fiiechan writes its arguments into the directory /news/spooi/out. going. T he-d flag may be used to specify a 
directory the program should change to before starting. 

If the -p flag is used, the program will write a line containing its process ID (in text) to the specified fi le. 

If fiiechan is invoked with -f 2 and given the following input: 

news/software/b/132 <1643@munnari.oz.au>foo uunet 
news/software/b/133 <102060@litchi.foo.com> uunet munnari 
comp/sources/unix/2002 <999@news.foo.com>foo uunet munnari 

Then the file foo will have these lines: 

news/software/b/132 <1643@munnari.oz.au> 
comp/sources/unix/2002 <999@news.foo.com> 

Thefile munnari will have these lines: 

news/software/b/133 <102060@litchi.foo.com> 
comp/sources/unix/2002 <999@news.foo.com> 

Thefileuunet will have these lines: 

news/software/b/132 <1643@munnari.oz.au> 
news/software/b/133 <102060@litchi.foo.com> 
comp/sources/unix/2002 <999@news.foo.com> 

Because the time window in which a file is open is very small, complicated flushing and locking protocols are not needed; a 
mv(l) followed by a sieep(l) for a couple of seconds is sufficient. 

A map file may be specified by using the-m flag. Blank lines and lines starting with anumbersign (#) areignored. All other 
lines should have two hostnames separated by a colon. The first field is the name that may appear in the input stream; the 
second field names the file to be used when the name in the first field appears For example, the following map file may be 
used to map the short namesto the full domain names 

# This is a comment uunet:news.uu.net fooifoo.com munnari:munnari.oz.au 


HISTORY 

W ritten by Robert Elz (kre@munnari.oz.au); flags added by Rich $alz (rsaiz@uunet.uu.net). 

SEE ALSO 

buff chan(8), innd(8), newsfeeds(5) 

fsck 

fsck—Check and repair a Linux filesystem. 

SYNOPSIS 

fsck [ -AVRTN ][-s ][ -t fstype ] [fs ■ opti ons ] filesys [ ... ] 





DESCRIPTION 

fsck is used to check and optionally repair a Linux filesystem, fiiesys is either the device name (such as/dev/hdai or /dev/ 
sdb2) or the mount point (such as /, /usr, or /home) for the filesystem. If this fsck has several filesystems on different 
physical disk drives to check, this fsck will try to run them in parallel. This reduces thetotal amount time it takes to check 
all of the filesystems because fsck takes advantage of the parallelism of multiple disk spindles 
Theexit code returned by fsck isthesum of the following conditions: 

0 No errors 

1 Filesystem errors corrected 

2 System should be rebooted 

4 Fi lesystem errors left uncorrected 

8 Operational error 

16 U sage or syntax error 

128 Shared library error 

The exit code returned when all filesystems are checked using the - a option is the bitwise or of theexit codes for each file 
system that is checked. 

In actuality, fsck is simply a front end for the various filesystem checkers (fsck.fstype) available under Linux.The 
filesystem-specific checker issearched for in /sbin first, then in /etc/fs and /etc, and finally in thedirectorieslisted in the 
path environment variable. Please see the filesystem-specific checker manual pages for further details 


OPTIONS 


-N 


-tfstype 


Walk through the /etc/f stab file and try to check all filesystems in one run. This 
option istypically used from the ie tc/rc system initialization file instead of 
multiple commands for checking a single file system. 

When checking all filesystems with the -a flag, skip the root file system (in case it's 
already mounted read-write). 

Don't show the title on startup. 

D on't execute; just show what would be done 

Serialize fsck operations. This isa good idea if you checking multi pie filesystems in 
and the checkers are in an interactive mode (N ote e2f sck runs in an interactive 
mode by default. To make e2fsck run in a non-interactive mode, you must either 
specify the -p or -a option, if you want errors to be corrected automatically, or the - 
n option if you do not.) 

Produce verbose output, including all filesystem-specific commands that are 
executed. 

Specifies the type of filesystem to be checked. When the - a flag is specified, only 
filesystems that match fstype are checked. If fstype is prefixed with no, only 
filesystems whose filesystem do not match fstype are checked. 

Usually, thefilesystem typeisdeduced by searching forn i esys in the /etc/fstab 
file and using the corresponding entry. If the type can not be deduced, fsck will use 
the type specified by the -t option if it specifiesa unique filesystem type. If thistype 
is not available the the default filesystem type (currently ext2) is used. 

Any options that are not understood by fsck, or that follow the - option are treated 
as filesystem-specific optionsto be passed to the filesystem-specific checker. 
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Currently, standardized filesystem-specific options are somewhat in flux. Although not guaranteed, thefollowing options are 
supported by most filesystem checkers: 

-a Automatically repair the filesystem without any questions (Use this option with caution.) Note 

that e2fsck supports -a for backwards compatibility only. This option is mapped to e2fsck’s -p 
option, which i s safe to use, unlike the -a option that most filesystem checkers support. 

-r Interactively repair thefilesystem (ask for confirmations). N ote: It isgenerally a bad idea to use 

thisoption if multi pie fsck'sare run in parallel. Also note that this is e2fsck default behavior; it 
supports this option for backwards compatibility reasons only. 


AUTHOR 

TheodoreTs'o (tytso@mit.edu) 

The manual page was shamelessly adapted from David Engel and Fred van Kempen's generic fsok front-end program, which 
in turn was shamelessly adapted from Remy Card's version for the ext2 filesystem. 

FILES 

/etc/fstab 


SEE ALSO 

fstab(5), mkfs(8), fsck.minix(8), fsck.ext2(8) Or e2fsck(8), fsck.xiafs(8) 


Verson 0.5b, N ovember!994 


fsck.minix 

fsck.minix-A filesystem consistency checker for Linux. 

SYNOPSIS 

fsck.minix [ -larvsmf ] device 

DESCRIPTION 

fsck.minix performs a consistency check for the Linux M IN IX filesystem. The current version supports the 14 character and 
30 character filename options. 

The program assumes the filesystem isquiescent. fsck.minix should not be used on a mounted device unless you can be sure 
nobody is writing to it (and remember that the kernel can write to it when it searches for files). 

Thedevicewill usually havethefollowingform: 

/dev/hda[1-8] 

/dev/hdb[1-8] 

/dev/sda[1-8] 

/dev/sdb[1-8] 

If thefilesystem was changed (that is, repaired), then fsck.minix will print File system has changed and will sync(2) three 
ti mes before exiting. Because Linux does not currently have raw devices, there is no need to reboot at this time (versus a 
system that does have raw devices). 

WARNING 

fsck.minix should not beused on a mounted filesystem. Using fsck.minix on a mounted filesystem is very dangerous due to 
the possibility that deleted files are still in use and can seriously damage a perfectly good filesystem! If you absolutely have to 
run fsck.minix on a mounted filesystem (that is, the root filesystem), make sure nothing is writing to the disk and that no 
files are "zombies" waiting for deletion. 
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OPTIONS 

-i Lists all filename. 

-r Performs interactive repairs 

-a Performsautomatic repairs (this option implies -r) and serve to answer all of the questions asked with the 

default. Note that this can be extremely dangerous in the case of extensive filesystem damage 
■v Verbose. 

-s Outputs super-block information. 

-m ActivateM INIX-like"modenot cleared" warnings. 

-t Force filesystem check even if the filesystem was marked as valid. (This marking is done by the kernel 

when thefilesystem is unmounted.) 

SEE ALSO 

fsck(8), fsck.ext(8), fsck.ext2(8), fsck.xiafs(8), mkfs(8), mkfs.minix(8), mkfs.ext(8), mkfs.ext2(8), mkfs.xiafs(8), reboot(8) 

DIAGNOSTICS 

There arenumerous diagnostic messages. The ones mentioned here are the most commonly seen in normal usage 
If thedevicedoes not exist, fsck.minix will print unable to read super block. If the device exists but is not a M IN IX 
filesystem, fsck.minix Will print Bad magic number in super-block. 

EXIT CODES 

The exit code returned by fsck.minix is the sum of the following: 

0 N o errors 

3 Filesystem errors corrected; system should be rebooted if filesystem was mounted. 

4 Filesystem errors left uncorrected. 

8 Operational error. 

i6 U sage or syntax error. 

In point of fact, only 0,3,4,7,8, and ie can ever be returned. 

AUTHOR 

LinusTorvalds (torvaids@cs.heisinki.fi). Error code values by Rik Faith (faith@cs.unc.edu). Added support for filesystem 
valid flag: Dr. Wettstein (greg%wind. uucp@piains.nodak.edu). Check to prevent fsck of mounted filesystem added by Daniel 
Quinlan (quinlan@yggdrasil.com). 

Linux 0.99,10 January 1994 
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ftpd— DARPA Internet FileTransfer Protocol server. 

SYNOPSIS 

ftpd [-d] [-1] [-t timeout] [ -T maxtimeout] 

DESCRIPTION 

ftpd isthe DARPA Internet File Transfer Protocol server process The server uses the TCP protocol and listens at the port 
specified in the FTP service specification; see services(5). 
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Available options: 

-d Debugging information is written to the syslog. 

-l E ach FT P 1 session is logged in the syslog. 

-t The inactivity timeout period is set to timeout seconds (The default is 15 minutes.) 

-t A client can also request a different timeout period; the maximum period allowed can be set to timeout 

seconds with the -t option. The default limit is2 hours. 

T he FT P server currently supports the following FT P requests; case is not distinguished. 

Request Description 

abor Abort previous command 

acct Specify account (ignored) 

allo Allocate storage (vacuously) 

appe Append to a file 

cdup Change to parent of current working directory 

cwd Changeworkingdirectory 

dele Delete a file 

help Give help information 

list Give list files in a directory (" is -igA 11 ) 

mkd Make a directory 

mdtm Show last modification time of file 

mode Specify data transfer mode 

nlst G ive name list of filesin directory 

noop Do nothing 

pass Specify password 

pasv P repare for server-to-server transfer 

port Specify data connection port 

pwd Print the current working directory 

quit Terminate session 

rest Restart incomplete transfer 

retr Retrieve a file 

rmd Remove a directory 

rnfr Specify rename-from filename 

rnto Specify rename-to filename 

site N onstandard commands (see next section) 

size Return size of file 

stat R etu rn status of server 

stor Store a file 

stou Storea file with a unique name 

stru Specify data transfer structure 

syst show operating system type of server system 

type specify data transfer type 

user specify username 

xcup change to parent of current working directory (deprecated) 
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Request Desjiption 

xcwd change working directory (deprecated) 

xmkd make a directory (deprecated) 

xpwd print the current working directory (deprecated) 

xrmd remove a directory (deprecated) 

The following non-standard or U N IX-specific commands are supported by the site request: 


Request Description 


Example 


Change umask 
Setidletimer 
Change mode of a file 
Give help information 


SITE UMASK 002 
SITE IDLE 60 
SITE CHMOD 755 
SITE HELP 


The remaining FTP requests specified in Internet RFC 959 are recognized but not implemented, mdtm and size are not 
specified in RFC 959 but will appear in the next updated FTP RFC. 

The FTP server will abort an active file transfer only when theABOR command is preceded by a Telnet "Interrupt Process" 

(IP) signal and aTelnet "Synch" signal in the command Telnet stream, asdescribed in Internet RFC 959. If asTAT 

command is received during a data transfer, preceded by a Telnet IP and synch, transfer status will be returned. 

ftpd interpretsfilenames according to theglobbing conventions used by csh(l). This allows users to utilize the 

metacharacters Li &*?[]. 

ftpd authenticates users according to four rules: 

The username must be in the password database and nothaveanull password. In this case a password must be provided 
by the client before any file operations may be performed. 

The username must not appear in the file (see ftpusers(5)). 

The user must have a standard shell returned by getusersheii(3). 

If the username isanonymous or FTP, an anonymous FTP account must be present in the password file (user FTP). In 
this case, the user is allowed to login by specifying any password. (By convention, thisis given as thedient host's name.) 

In the last case ftpd takes special measures to restrict the client's access privileges The server performs a chroot(2) command 
to the home directory of the FT P user. So that system security is not breached, it is recommended that the FT P subtree be 
constructed with care; thefollowing rules are recommended: 

■ftp M ake the home directory owned by root and unwritable by anyone 

■ftp/bin M ake this directory owned by root and unwritable by anyone The program is(l) must be present to 

support the list command. This program should have mode in. 

-ftp/etc Make this directory owned by root and unwritable by anyone T he files passwd(5) and group(5) must be 

present for the is command to beableto produce owner names rather than numbers. The password field 
in passwd isnot used and should not contain real encrypted passwords. These files should be mode 444 and 
owned by root. Don't use the system's/etc/passwd file as the password file or the system's/etc/group file 
as the group file in the-ftp/etc directory. 

pa -ftp/pub M ake this directory mode 755 and owned by root. Create a subdirectory in -ftp/pub with the appropriate 
mode (777 or 733) if you want to allow normal users to upload files. 


SEE ALSO 

ftp(l), getusershell(3), ftpusers(5), syslogd(8) 


BUGS 

The anonymous account is inherently dangerous and should avoided when possible 
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The server must run asthe super-user to create sockets with privileged port numbers. It maintains an effective user ID of the 
logged-in user, reverting to the super-user only when binding addresses to sockets The possible security holeshave been 
extensively scrutinized but are possibly incomplete 

HISTORY 

The command appeared in BSD 4.2. 

BSD 4.2,16 M arch 1991 

ifconfig 

ifconfig— Configure a network interface. 

SYNOPSIS 

ifconfig [i nterface ] 

ifconfig interface [aftype] options | address ... 

DESCRIPTION 

ifconfig isused to set up (and maintain thereafter) the kernel-resident network interfaces. It is used at boot time to configure 
most of them to a running state. After that, it is usually only needed when debugging or when system tuning is needed. 

If no arguments are given, ifconfig just displays the status of the currently defined interfaces If thesingle interface argument 
is given, it displays the status of the given interface only. Otherwise it assumes that things have to be set up. 

ADDRESS FAMILIES 

If the first argument after the interface name is recognized as the name of a supported address family, that address family is 
used for decoding and displaying all protocol addresses Currently supported addressfamilies include inet (TCP/IP, default) 
and ax25 (AM PR Packet Radio.) 

OPTIONS 

interface The name of theN ET interface. This usually is a name such aswd0, si3, or something like that: 

a devicedriver name followed by a unit number. 

up Thisflagcausestheinterfaceto be activated. It isimplicitly specified if theinterface isgiven a 

new address (see below). 

down Thisflag causes the driver for this interfaceto be shut down and is useful when things start 

going wrong. 

Harp Enable or disable the use of theARP protocol on this interface. If theminus(-) sign ispresent, 

theflagisturnedOFF. 

[ - jtraiiers Enableor disable the use of trailers on Ethernet frames This is not used in the current 

implementation of N ET. 

[ - jaiimuiti Enableor disable the promiscuous mode of the interface Thismeansthatall incoming frames 

get sent to the network layer of the system kernel, allowing for networking monitoring, 
metric n This parameter sets the interface metric. It is not used at present, but we implement it for the 

future 

mtu n This parameter sets the M aximum T ransfer U nit (M TU) of an interface For Ethernet, this is a 

number in the range of 1000-2000 (default is 1500). For SLIP, use something between 200 and 
4096. N ote that the current implementation does not handle IP fragmentation yet, so you'd 
better make the M T U large enough! 

dstaddr addr Set the "other end's" IP address in case of a point-to-point link, such asPPP. This keyword is 

obsoleted by the new pointopoint keyword. 
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netmask addr 


[-]broadcast [addr] 


[ -]pointopoint [addr] 


address 


FILES 

/dev/net/socket 


Sdt the IP network mask for this interface This value defaults to the usual class A, B, orC 
network mask (as deducted from the interface IP address), but it can be set to any value for the 
use of subnetting. 

If the address argument is also given, set the protocol broadcast address for this interface 
0 therwise, it only sets the iff_broadcast flag of the interface If the keyword was preceded by a 
minus(-) sign, then theflag iscleared instead. 

This keyword enables the point-to-point mode of an interface meaning that it is a direct link 
between two machines with nobody else listening on it. (Atleastwehopethatthisisthecase, 
grin :-).) 

If the address argument is also given, set the protocol address of the other side of the link, just 
like the obsolete dstaddr keyword does. Otherwise, it only sets the iff_pointopoint flag of the 
interface. If the keyword was preceded byaminus(-) sign, then theflag iscleared instead. 

Set the hardware address of this interface if the device driver supports this operation. The 
keyword must be followed by the name of the hardware class and the printable ASC11 
equivalent of the hardware address H ardware classes currently supported include ether 
(Ethernet), ax25 (AM PR AX.25), and ppp, although the latter is not really supported yet. 

The hostname or IP address(a hostname will be resolved into an IP address) of that interface. 
This parameter is required, although the syntax doesn't currently require it. 


BUGS 

N one so far, although the syntax checking could be better. 

AUTHOR 

Fred N . van Kempen (waltje@uwalt.nl.mugnet.org) 

6 October 1993 


inetd 

inetd-1 nterndt superserver. 

SYNOPSIS 

inetd [-d] [configuration file] 

DESCRIPTION 

inetd should be run at boot time by /etc/rc. local (see rc(8)). It then listens for connections on certain Internet sockets 
When a connection is found on one of its sockets it decides what service the socket corresponds to and invokes a program to 
service the request. After the program isfinished, it continues to listen on the socket (except in some cases which are 
described later). Essentially, inetd allows running one daemon to invoke several others, reducing load on the system. 

The option availablefor inetd: 

-d Turns on debugging. 

Upon execution, inetd reads its configuration information from a configuration file which, by default, is/etc/inetd.conf. 
There must bean entry for each field of the configuration file with entries for each field separated by a tab or a space. 

C omments are denoted by a # at the beginning of a line. T here must be an entry for each field. T he fields of the configura¬ 
tion file are as follows 
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socket type 
protocol 

wait/nowait[ .max] 
user].group] 
server program 
server program arguments 

T o specify an Sun-RPC based service, the entry would contain these fields 

service name/version 

socket type 

rpc/protocol 

wait/nowait].max] 

user].group] 

server program 

server program arguments 

T he service-name entry is the name of a valid service in the file /etc/services. For internal services, the service name must 
be the official nameof the service (that is, thefirst entry in /etc/services). When used to specify a Sun-RPC based service 
thisfield isavalid RPC service namein the file/etc/rpc. The part on the right of the/ istheRPC version number. This can 
simply be a single numeric argument or a range of versions. A range is bounded by the low version to the high version 

- rusers/1 -3. 

The socket type should be one of stream, dgram, raw, rdm, orseqpacket, depending on whether the socket is a stream, 
datagram, raw, reliably delivered message, or sequenced packet socket. 

The protocol must be a valid protocol as given in /etc/protocois. Examples might be top or udp. R pc-based services are 
specified with the rpc/tcp or rpc/udp service type. 

The wait/nowait entry is applicable to datagram sockets only. (Other sockets should havea nowait entry in this space) If a 
datagram server connects to its peer, freeing the socket so inetd can receive further messages on the socket, it issaid to be a 
multithreaded server and should use the nowait entry. For datagram servers that process all incoming datagramson a socket 
and eventually timeout, the server issaid to be single-threaded and should use a wait entry. comsat(8), biff(l), and taikd(8) 
are examples of the latter type of datagram server. Tftpd(8) is an exception; it is a datagram server that establishes pseudo¬ 
connections. 

It must be listed as wait in order to avoid a race; the server reads the first packet, creates a new socket, and then forks and 
exits to allow inetd to check for new service requests to spawn new servers The optional max suffix (separated from wait or 
nowait by a dot) specifies the maximum number of server instances that may be spawned from inetd within an interval of 60 
seconds When omitted, max defaults to 40. 

The user entry should contain the username of the user as whom the server should run. This allows for servers to be given 
less permission than root. An optional group name can be specified by appending a dot to the username followed by the 
group name. Thisallowsfor servers to run with a different (primary) group ID than specified in the password file If a group 
isspecified and the user is not root, the supplementary groups associated with that user will still be set. 

The server-program entry should contain the pathname of the program that is to be executed by inetd when a request is 
found on its socket. If inetd provides this service internally, this entry should be internal. 

The server program arguments should appear just as arguments normally do, starting with argv[0], which is the name of the 
program. If the service is provided internally, theword internal should take the place of this entry, 
inetd provides several trivial services internally by use of routines within itself. These services are echo, discard, chargen 
(character generator), daytime (human readable time), and time (machine readable timein theform of the number of seconds 
since midnight, J anuary 1,1900). All of these servicesareTCP based. For details of these services, consult the appropriate 
RFC from the N etwork Information Center. 
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inetd rereads its configuration file when it receives a hangup signal, sighup. Services may be added, deleted, or modified 
when the configuration file is reread, inetd creates a file/etc/inetd. pi d that contains its process identifier. 

SEE ALSO 

comsat(8), fingerd(8), ftpd(8), rexecd(8), rlogind(8), rshd(8), telnetd(8), tftpd(8) 

HISTORY 

The command appeared in BSD 4.3. Support for Sun-RPC based services is modeled after that provided by Sun-OS 4.1. 

BSD 4.3,16 M arch 1991 


init,telinit 

imt, telinit— Process control initialization. 

SYNOPSIS 

/sbin/init [ -t sec ][0123456SsQq ] 

/sbin/telinit [ -t sec ][0123456sSQqabc ] 

DESCRIPTION 

init 

init isthefather of all processes. Its primary roleisto create processes from a script stored in thefile /etc/inittab (see 
inittab(5)).Thisfile usually has entries that cause init to spawn gettys on each line that users can login. It also controls 
autonomous processes required by any particular system. 

A run level is a software configuration of the system that allowsonly a selected group of processes to exist. The processes 
spawned by init for each of these run levels are defined in the/etc/inittab file init can be in oneof eight run levels, 06 and 
sors.Therun level ischanged by having a privileged user run /sbin/teiinit, which sends appropriate signalsto init, telling 
it which run level to change to. 

After init is invoked as the last step of the kernel booting, it looks for the file/etc/inittab to see if there is an entry of the 
type inttdefauit (see inittab(5)). initdefauit determines the initial run level of the system. If there is no such entry or no 
/etc/inittab at all, a run level must be entered at the system console. 

Run level sor s brings the system to single-user mode and does not require an /etc/initttab file. In single-user mode 
/bin/sh is invoked on /dev/console. 

/dev/consoie need not necessarily be the physical system console. When init istoldto enter singleuser mode or run level 1 
(either directly, by init s, or by telling shutdown to enter maintenance mode), it will link theterminal linethecommand 
was executed from to /dev/consoie. The device /dev/systty iscalled the physical system console and thedevice /dev/consoie 
is called the logical system console If the logical system console is not the physical system console, pressing the combination 
Ctrl+Alt+D el on the physical system console will forcea relink of /dev/consoie to /dev/systty. A terminal linecan only 
become the logical console if it's listed in thefile /etc/securetty. All this is in preparation of the day that the Linux kernel 
will support serial consoles. 

Beware: If you want to run x or anything else that is aware of Virtual Consoles, the logical system console (/dev/consoie) 
needs to be the same as the physical system console (/dev/systty). 

When entering single-user mode init reads the console's iocti(2) states from /etc/iocti.save. If this file does not exist, init 
initializes the line at 9600 baud and with clocal settings. When init leaves singleuser mode, it stores the console's iocti 
settings in thisfile so it can reuse them for the next singleuser session. If the logical system console ischanged to another 
terminal line the settings of thelinefrom which the init or telinit command was given are stored in /etc/iocti.save too, 
so that theterminal line will be initialized correctly in singleuser mode. 
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When entering a multi-user mode the first time, imt performs the boot and bootwatt entries to allow filesystems to be 
mounted before users can log in. Then all entries matching the run level are processed. 

Each time a child terminates, imt records the fact and the reason it died in /etc/utmp and /var/adm/wtmp if these files exist. 
After it has spawned all the processes specified, imt waits for one of its descendant processes to die a powerfail signal, or a 
signal by /sbin/teiimt to change thesystem's run level. W hen one of these three conditions occurs, it reexamines the 
/etc/inittab file N ew entries can be added to thisfile at any time. However, init still waits for one of the three conditions 
to occur. T o provide for an instantaneous response the q or q command can wake up init to reexaminethe /etc/inittab 
file. 

If init is not in singleuser mode and receives a powerfai I signal, special powerfail entries are invoked. 

When init is requested to change the run level, it sends the warning signal sigterm to all processes that are undefined in the 
new run level. Itthen waits 20 seconds before forcibly terminating these processes via the kill signal sigkill. 

N otethat init assumes that all these processes (and their descendants) remain in the same process group that init originally 
created for them. If any process changes its process group affiliation, it will not receive these signals Such processes need to 
determinated separately. 

telinit 

/sbin/teiinit is linked to /sbin/init. 11 takes a one-character argument and signals imt to perform the appropriate action. 
Thefollowing arguments serve as directives to /sbin/teiimt: 

0, i, 2,3,4,5, or 6 Tell /sbin/init to switch to the specified run level. 

a, b, c Tell /sbin/init to processonlythose/etc/imttab file entries having run level a, b, or c. 

q or q Tell /sbin/init to re-examinethe /etc/imttab file, 

s or s Tell /sbin/init to switch to single-user mode. 

/sbin/teiinit can also tell init how much time it should wait between sending processes the term and the kill signal; the 
default is 20 seconds, but it can be changed by the -t sec option. 

/sbin/teiimt can be invoked only by users with appropriate privileges 

RUN LEVELS 

Run levels 0,1, and 6 are reserved. Run level 0 isused to halt the system, run level 6 is used to reboot the system, and run 
level 1 isused to get the system down into single-user mode. Run level s is not really meant to be used directly but should be 
used by scripts that are executed when entering run level 1. For more information on this see the man pages for shutdown(l) 
and inittab(5). 

FILES 

/etc/inittab 

/dev/console 

/dev/systty 

/etc/ioctl.save 

/etc/utmp 

/var/adm/wtmp 

CONFORMING TO 

imt is compatible with the System V init. The scripts that are used with it, however, are mostly modeled after the BSD 
startup scripts. There are startup scripts available that let Linux boot more like a System V system, but most people find 
them too complex. 

WARNINGS 

imt assumes that processes and descendants of processes remain in the same process group that was originally created for 
them. If the processes change their group, in it can't kill them and you might end up with two processes reading from one 
terminal line 
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DIAGNOSTICS 

If /sbin/init finds that it is continuously respawning an entry more than ten timesintwo minutes, it will assume that there 
is an error in the command string, generate an error message on the system console and refuse to respawn this entry until 
either five minutes has elapsed or it receives a signal. This prevents it from eating up system resources when someone makes a 
typographical error in the/etc/imttab file or the program for the entry is removed. 

AUTHOR 

M iquel van Smoorenburg (miqueis@drinkei.ni.mugnet.org); initial manual page by M ichael H aardt 

(u31b3hs@pool.informatik.rwth-aachen.de). 

SEE ALSO 

getty(l), login(l), sh(l), who(l), shutdown(l), kill(2), inittab(5), utmp(5) 

19 January 1994 
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innd, inndstart— InterN dtN ewsdaemon. 

SYNOPSIS 

innd [ -a ][ -c days ][-d ][-f ][-i count ][-o count ][-1 size ] 

[-m mode ][-n flag ] [ -p port ][-r ][-s ][-S host ][-t timeout ][-u ][-x ] 
inndstart [flags ] 

DESCRIPTION 

innd, the I nterN etN ews daemon, handles all incoming N N TP feeds. It reads the active(5), newsfeeds(5), and hosts. nntp(5) 
files into memory. It then opens the N N TP port to receive articles from remote sites, a U N IX-domain stream socket to 
receive articles from local processes such asnnrpd(8) and rnews(l), and aUN IX-domain datagram socket for use by 
ctiinnd(8) to direct the server to perform certain actions It also opens the history(5) database and two log files to replace its 
standard output and standard error. If the -p flag is used, then the N NTP port is assumed to be open on the specified 
descriptor. (If thisflag is used, then innd assumes it is running with the proper permissionsand it does not call chom(2) on 
any files or directories it creates) 

Once the files and sockets have been opened, innd waits for connections and data to be ready on its ports by using seiect(2) 
and non-blocking I/O. If no data is avail able, then it flushes its in-core data structures. The default number of seconds to 
timeout before flushing is 300. This timeout may be changed by using the-t flag. 

To limit the number of incoming N NTP connections use the-i flag. A value of 0 suppresses this check. 

To limit the number of files that are kept open for outgoing file feeds use the-0 flag. Thedefault isthe number of available 
descriptors minus some reserved for internal use. 

T 0 limit the size of an article, use the -1 flag. If thisflag is used, then any article bigger than size bytes is rgected. T he 
default is no checking, which can also be obtained by using a value of 0. 

innd r^ects articles that are too old. Although this behavior can be controlled by the history database, occasionally a site 
dumps a batch of very old news back onto the network. Use the-c flag to specify a cutoff. For example -021 rejectsany 
articles that were posted more than 21 days ago. A value of 0 suppresses this check. 

innd usually puts itself into the background, sets its standard output and error to log files, and disassociates itself from the 
terminal. U sing the -d flag instructs the server to not do this, whereas using the -f flag j ust leaves the server running the 
foreground. The logs are usually buffered; use the-u flag to have them unbuffered. 

T 0 start theserver in a paused or throttled state (see ctiinnd(8)) use the -m flag to set the initial running mode The 
argument should start with a single letter g, p, or t to emulate the go, pause, or throttle commands 
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If the -r flag isused, the server renumbers theacti vefile as if a renumber command were sent. 

If the -s flag isused, then innd does not do any work but instead just checks the syntax of the news-feeds file. It exits with an 
error status if there are any errors; the actual errors are reported in sysiog(3). 

If innd gdtsan NOSPC error (see intro(2)) while trying to write the active file, an article file, or the history database it sends 
itself a throttle command. This also happens if it gets too many I/O errors while writing to any files. 

Any subprocesses spawned by the server get a mce(2) value of 10. 

The-n flag specifies whether pausing or throttling the server should also disable future news-reading processes A value of y 
makes news readers act as the server, a value of n allows news reading even when the server is not running. 

If the-s flag isused, then innd runs in slave mode. When running as a slave, the server only accepts articles from the 
specified host, which must use the xrepiic protocol extension. N ote that either the host must appear in the hosts, nntp file or 
the server must be started with the-a flag. 

By default, if a host is not mentioned in the hosts, nntp file then the connection is handed off to nnrpd. If the-a flag isused, 
then any host can connect and transfer articles. 

If the-x flag isused, then a Xref header is added to all articles even if they are not cross-posted, 
inndstart is a small front-end program that opens the N NTP port, sets its user ID and group ID to the news maintainer, 
and then executes innd with the-p flag and a minimal secure environment. This is a small, easily understood front-end 
program that can be used if a site does not want to run innd with root privileges. 

CONTROL MESSAGES 

Arriving articles that have a Control header or have a Subject header that starts with the five characters cmsg are called control 
messages Except for the cancel message these messages are implemented by external programsin the/news/bin/controi 
directory. (Cancel messages update the history database, so they must be handled internally; the cost of synching, locking, 
and then unlocking istoo high, given the number of cancel messages that are received.) 

W hen a control message arrives, the first word of the text is converted to lowercase and used as the name of the program to 
execute; if the named program does not exist, then a program named default is executed. 

All control programs are invoked with four parameters The first is the address of the person who posted the message; this is 
taken from the Sender header. If that header isempty, then it istaken from the From header. The second parameter is the 
address to send replies to; this is taken from the Reply-To header. If that header is empty, then the poster's address is used. 
Thethird parameter isa name under which the article isfiled, relative to the news spool directory. Thefourth parameter is 
the host that sent the article, as specified on thePath line. 

The distribution of control messageisalso different from those of standard articles. 

Control messages are usually filed in the newsgroup named control. They can be filed in subgroups, however, based on the 
control message command. For example a newgroup message isfiled in control, newgroup if that group exists, otherwise it will 
be filed in control. 

Sites may explicitly have the "control" newsgroup in their subscription list, although it is usually best to exclude it. If a 
control message is posted to a group whose name ends with thefour characters .cti, then the suffix is stripped off and what 
is left is used asthegroup name. For example, a cancel message posted to news, admin, cti will be sent to all sites that 
subscribed control or news.admin, newgroup and rmgroup messages receive additional special treatment. If the message is 
approved and posted to the name of the group being created or removed, then the message is sent to all sites whose 
subscription patterns would cause them to receive articles posted in that group. 

If an article is posted to a newsgroup that starts with the three letters to., it gets special treatment if the newsgroup does not 
exist in the active file. The article is filed into the newsgroup to and it is sent to the first site named after the prefix. For 
example, a posting to to.uunet isfiled in to and sent to the site uunet. 

PROTOCOL DIFFERENCES 

innd implements the N N T P commands defined in RFC 977 with the following differences: 
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■ The list may be followed by an optional active, active.times, or newsgroups argument. Thiscommon extension isnot 
fully supported; see nnrpd(8). 

■ Theauthinto user and authinfo pass commands are implemented. These are based on the reference U NIX implemen¬ 
tation; no other documentation is available 

■ A new command, mode reader, is provided. This command causes the server to pass the connection on to nnrpd. The 
command mode query is intended for future use and is currently treated the same way. 

■ A new command, xreplic news. group:art[, news. group:art], is provided. This is Similar to the ihave command (the 
same reply codes are used) except for the data that follows the command word. T he data consists of entries separated by 
a single comma. Each entry consists of a newsgroup name, a colon, and an article number. Once processed, the article is 
filed in the newsgroup and article numbers specified in thecommand. 

■ A new command, xpath messaged, is provided. The server responds with a223 response and a space-separated list of 
filenames where the article was filed. 

■ The only other commands implemented are head, help, ihave, quit, and stat. 

HEADER MODIFICATIONS 

innd modifies asfew article headers as possible, although it could be better in thisarea. 

Thefollowing headers, if present, are removed: 

Date-Received 

Posted 

Posting-Version 

Recdved 

Relay-Version 

Empty headers and headers that consist of nothing but whitespace are also dropped. 

The local site's name and an exclamation point are prepended to the Path header. 

TheXref header isremoved. Ifthearticleiscross-posted, anew header isgenerated. 

The Lines header is added if it is missing. 

innd doesnot rewrite incorrect headers. For example it does not replace an incorrect Lines header but rejects thearticle 

LOGGING 

innd reports all incoming articles in its log file. Thisisatext file with a variable number of space-separated fields in oneofthe 
following formats: 

mon dd hh:mm:ss.mmin + feed <Message-ID>site... 
mon dd hh:mm:ss.mmm j feed <Message-ID> site... 
mon dd hh:mm:ss.mmm c feed <Message-ID> site... 
mon dd hh:mm:ss.mmm - feed <Message-ID> reason... 

Thefirst three fields are the date and time to millisecond resolution. T he fifth field is the site that sent the article (based on 
the Path header), and thesixth field isthe article's M essage-l D; they will contain a question mark if the information isnot 
available. 

Thefourth field indicateswhether the article was accepted. If it is a plussign, the article was accepted. If it isthe letter j, the 
article was accepted, but all of newsgroups have a j in their active field, so the article was filed into the "junk" newsgroup. If 
thefourth field isthe letter c, a cancel message was accepted before the original article arrived. In all three cases, thearticle 
has been accepted and the site... field containsthespace-separated list of sites to which the article is sent. 

If thefourth field is a minus sign, the article was rejected. T he reasons for rqecti on include 
%s header too long 
%s wants to cancel <ks> by %s 
Article exceeds local limit of %s bytes 
Article posted in thefuture- %s 
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Bad%s header 
Can't write history 
D uplicate 
Duplicate %s header 
EOF in headers 
Linecount %s !=%s +- %s 
M issing%s header 
N o body 

N o colon-space in %s header 
N o space 

Space before colon in %s header 
T oo old- %s 
U napproved for %s 
U nwanted newsgroup %s 
Unwanted distribution %s 
W hitespace in "N ewsgroups" header- %s 
W here %s, above is replaced by more specific information. 

Note that if an article is accepted and none of the newsgroups are valid, it islogged with both two lines, a j line and a minus 
sign line. 

innd also makes extensive reports through sysiog. Thefirst word of the log message isthe name of the site if the entry is site- 
specific (such as a connected message). T he first word is me if the message relates to the server itself, such as when a read error 
occurs. 

If the second word isthefour letters cant, an error is being reported. In this case the next two words generally name the 
system call or library routine that failed and the object upon which the action was performed. The rest of the line might 
contain other information. 

In other cases, the second word attempts to summarize what change has been made, and the rest of the line gives more 
specific information. The word internal generally indicates an internal logic error. 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

active(5), ctlinnd(8), dbz(3z), history(5), hosts.nntp(5), inn.conf(5), newsfeeds(5), nnrpd(8), rnews(l), syslog(8) 

innxmit 

innxmit— Send U sendt articles to a remote N N T P server. 

SYNOPSIS 

innxmit [ -A alt.spool ] [-a ][-d ][-M ][-r ][-t timeout ] 

[-T timeout ][-p ][-S ] host file 

DESCRIPTION 

innxmit connects to theN NTP server at the specified host and sends it the articles specified in the batchfile named file. It is 
usually invoked by a script run out of cron(8) that usesshiock(l) to lock the hostname followed by actiinnd(8) command to 
flush the batchfile. 



innxmit usually blocks until the connection is made. T o specify a timeout on how long to try to make the connection, use the 
-t flag. T o specify the total amount of time that should be allowed for article transfers, usethe-T flag. The default isto wait 
until an I/O error occurs or all the articles have been transferred. If the -t flag is used, the timeischecked just before an 
article is started; it does not abort a transfer that is in progress Both values are measured in seconds 
If the file is not an absolute pathname it is taken relative to the/news/spooi/out. going directory. It is usually written by 
specifying the wnm flags in thenewsfeeds(5) file Each line in the batchfile should be in one of the following formats: 
filename Message-1 D 


The filename field names the article to be sent. If it is not an absolute pathname it is taken relative to the news spool 
directory, /news/spooi. If the Message -id field is not specified, it is obtained by scanning the article The filename and 
Message - id fields are separated by a space. 

If a communication error such asawrite(2) failure occurs, innxmit stops sending and rewrites the batchfile to contain the 
current article and any other unsent articles 

If the remote server sends an unexpected reply code, innxmit requeues the article and proceeds. U se the-r flag if the article 
should not be requeued. 

Upon exit, innxmit reports transfer and C PU usage statistics via sysiog(3). If the-v flag is used, they are also printed on the 
standard output. If all articles were sent successfully, innxmit removes the batchfile; otherwise; it rewrites it to contain the list 
of unsent articles If no articles were sent or rqected, the file is left untouched. This can cause the batchfile to grow 
excessively large if many articles have been expired and there are communication problems. T o always rewrite the batchfile 
use the-a flag. If the -p flag is given, then no connection is made and the batchfile is purged of entries that refer to filesthat 
no longer exist. This implies the-a flag. 

If the -s flag isgiven, then innxmit offers articles to the specified host using the xrepiic protocol extension described in 
innd(8). To usethisflag, the input file must contain the history data (commas are transliterated to spaces by the server). For 
thisflagto be used, the input must contain the necessary history entries. This is usually done by setting up awnR entry in the 
newsfeeds file 

Use the-d flag to print debugging information on standard error. This shows the protocol transactions between innxmit and 
the N N T P server on the remote host. 

If the -m flag is used, innxmit scans an article's headers before sending it. If the article appears to be a M IM E article that is not 
in seven-bit format, thearticle issent in "quoted-printable;' form. 

The -a flag may be used to specify an alternate spool directory to use if the article is not found; this is usually an N FS- 
mounted spool directory of a master server with longer expiration times. 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

ctlinnd(8), innd(8), newsfeeds(5), shlock(l) 

ipcrm 

ipcrm— Remove ipc facilities. 

SYNOPSIS 

ipcrm [ shm ] msg | sem ] i d 

DESCRIPTION 

ipcrm removes the resource specified by i d. 
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SEE ALSO 

ipcs(8) 

AUTHOR 

Krishna Balasubramanian (baiasub@cis.ohio-state.edu) 


Linux 0.99, 9 October 1993 


ipcs 

ipcs— Provide information on ipc facilities. 

SYNOPSIS 

ipcs [ -asmq ] [ -tclup ] 

DESCRIPTION 

ipcs provides information on the ipc facilities for which the calling process has read access 
The -i option allows a specific resource i d to be specified. Only information on thisi d is printed. 

Resources may be specified as follows: 

-m Shared memory segments 

-q M essage queues 

-s Semaphore arrays 

-a All (thisisthedefault) 

T he output format may be specified as follows: 

-t Time 

-p PID 

-c Creator 

-l Limits 

-u Summary 

SEE ALSO 

ipcrm(8) 

AUTHOR 

Krishna Balasubramanian (baiasub@cis.ohio-state.edu) 

Linux 0.99, 9 October 1993 


kbdrate 

kbdrate— Resdt the keyboard repeat rate and delay time. 

SYNOPSIS 


kbdrate [ -s ] [ -r rate ][-c 




klogd 


DESCRIPTION 

kbdrate is used to change the IBM keyboard repeat rate and delay time The delay istheamountoftimethatakey must be 
pressed before it starts to repeat. U sing kbdrate without any options resets the rate to 10.9 characters per second (cps) and 
the del ay to 250 milliseconds (ms). T hese are the IB M defaults 

OPTIONS 

■s Silent. No messages are printed. 

-r rate C hange the keyboard repeat rate to r at e cps The allowable range isfrom 2.0to 30.0 cps. Only certain 

specific values are possible, and the program selects the nearest possible value to the one specified. The 
possible values are given, in characters per second, as follows: 2.0,2.1,2.3,2.5,2.7,3.0,3.3,3.7,4.0,4.3, 

4.6, 5.0, 5.5, 6.0, 6.7, 7.5, 8.0, 8.6, 9.2, 10.0, 10.9, 12.0, 13.3, 15.0, 16.0, 17.1, 18.5, 20.0, 21.8, 24.0, 


-d delay Change the delay to del ay milliseconds. The allowable range is from 250 to 1000 ms buttheonly possible 

values (based on hardware restrictions) are 250 ms 500 ms, 750 ms and 1000 ms 

BUGS 

N ot all keyboards support all rates 
N ot all keyboards have the rates mapped in the same way. 

Setting the repeat rate on the Gateway A nyKey keyboard does not work. If someone with a G ateway figures out how to 
program the keyboard, please send mail to faith@cs.unc.edu. 

FILES 

/etc/rc.local 
/dev/port 


AUTHOR 

Rik Faith (faith@cs.unc.edu) 


Linuxl.1.19, 22 Junel994 


klogd 

kiogd— Kernel log daemon. 

SYNOPSIS 

klogd -c [n] -d -f [f name ] -os 

DESCRIPTION 

kiogd isa system daemon that intercepts and logs Linux kernel messages. 

OPTIONS 

-c Sets the default log level of console messages to [nj. 

-d Enables debugging mode This will generate a lot of output to stderr. 

-f Logs messages to the specified filename rather than to the sysiog facility. 

-0 Execute in one-shot mode. This causes kiogd to read and log all the messages that are found in the kernel 

message buffers. After a single read and log cycle, the daemon exits 
-s Force kiogd to usethesystem call interface to the kernel message buffers 
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OVERVIEW 

The functionality of kiogd has been typically incorporated into other versions of sysiogd, but this seems to beapoor place 
for it. In the modern Linux kernel, a number of kernel messaging issues such assourcingand prioritization must be 
addressed. I ncorporating kernel logging into a separate process appears to offer a cleaner separation of services 
In Linux, there are two potential sources of kernel log information: the /proc filesystem and the syscaii (sys_sysiog) 
interface, although ultimately they are one and the same kiogd isdesigned to choose whichever source of information isthe 
most appropriate. Itdoes thisby first checking for the presenceof amounted /proc filesystem. If thisisfound, the 
/proc/kmsg file isused as the source of kernel log information. If the proc filesystem is not mounted, kiogd uses a system call 
to obtain kernel messages The command-line switch (-s) can be used to force kiogd to use the system call interface as its 
messaging source. 

If kernel messages are directed through the sysiogd daemon, the kiogd daemon, as of version 1.1, has the ability to properly 
prioritize kernel messages Prioritization of the kernel messages was added at approximately the pii 3 level of the kernel. The 
raw kernel messages are of the form: 

<[0-7]>Somet hi ng said by the kernel. 

The priority of the kernel message is encoded as a single numeric digit enclosed inside the <> pair. The definitions of these 
values is given in the kernel include file kernel, h. When a message is received from the kernel, the kiogd daemon reads this 
priority level and assigns the appropriate priority level tothesysiog message. If file output (-f) is used, the prioritization 
sequence is left prepended to the kernel message. 

The kiogd daemon also allows the ability to alter the presentation of kernel messages to the system console Consequent with 
the prioritization of kernel messages was the inclusion of default messaging levels for the kernel. In a stock kernel, the default 
console log level is set to 7. Any messages with apriority level numerically lower than 7 (higher priority) appear on the 
console 

M essages of priority level 7 are considered to be debug messages and do not appear on the console. M any administrators, 
particularly in a multi-user environment, prefer that all kernel messages be handled by kiogd and either directed to a file or 
to the sysiogd daemon. This prevents nuisance messages such as line printer out of paper or disk change detected from 
cluttering the console 

By default, the kiogd daemon executes a system call to inhibit all kernel messages (except for panics) from being displayed on 
the console The-c a/vitch can be used to alter this behavior. The argument given to the-c a/vitch specifies the priority level 
of messages that are directed to the console. N ote that messages of a priority value lower than the indicated number are 
directed to the console. 

For example, to have the kernel display all messages with a priority level of 3 (kern err) or more severe the following 
command is executed: 

kiogd -c 4 

The definitions of the numeric values for kernel message are given in the file kernel, h, which can befound in the 
/usr/inciude/iinux directory if thekernel source are installed. These value parallel thesysiog priority value, which are 
defined in the file sysiog.h, found in the/usr/inciude/sys subdirectory. 

The kiogd daemon can also be used in a one-shot modefor reading the kernel message buffers. 0 ne-shot mode is selected by 
specifying the-0 switch on the command line Output is directed to either the sysiogd daemon or to an alternate file 
specified by the-f switch. 

For example, to read all thekernel messages after a system boot and record them in a file called krni.msg, the following 
command is given: 

kiogd -0 -f ./krni.msg 

SIGNAL HANDLING 

The kiogd daemon responds to six signals sighup, sigint, sigkill, sigterm, sigtstp, and sigcont. ThesiGiNT, sigkill, 
sigterm, and sighup signals cause the daemon to close its kernel log sources and terminate gracefully. 
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ThesiGTSTP and sigcont signals are used to start and stop kernel logging. Upon receipt of a sigtstp signal, the daemon closes 
its log sources and spins in an idle loop. Subsequent receipt of a sigcont signal causes the daemon to go through its 
initialization sequence and rechoose an input source. Using sigstop and sigcont in combination, the kernel log input can be 
rechosen without stopping and restarting the daemon. For example if the /proc filesystem is to be unmounted, the following 
command sequence should be used: 

# kill -TSTP pid 

# umount /proc 

# kill -CONT pid 

N otations will be made in the system logs with log info priority documenting the start/stop of logging. 

FILES 

/proc/kmsg 

BUGS 

Probably numerous. Well-formed context diffsappreciated. 

AUTHOR 

Dr. Greg Wdttstein (greg%wind. uucp@piains.nodak.edu), Enjellic Systems Development, 0 neology Research D ivision 
Computing Facility, Roger M arisCancer Center, Fargo, N D 58122. 

Verson 1.1, 28 January 1994 


lpc 

ipc—Line printer control program. 

SYNOPSIS 

lpc [command [argument ...]] 


DESCRIPTION 

ipc isused by the system administrator to control the operation of the line printer system. For each line printer configured in 
/etc/printcap, ipe may be used to 

■ Disable or enable a printer 

■ D isable or enablea printer'sspooling queue 

■ Rearrangetheorderofjobsin a spooling queue 

■ Find thestatusof printersand theirassociated spoolingqueuesand printer daemons 

Without any arguments, ipc prompts for commands from the standard input. If arguments are supplied, ipc interprets the 
first argument as a command and the remaining arguments as parameters to the command. The standard input may be 
redirected, causing ipc to read commands from file Commands may be abbreviated; the following is the list of recognized 
commands 


? [ command ... [help [ command 
Ic abort No all - printer 

clean No all - printer 

disable No all - printer 


Print a short description of each command specified in the argument 
list or, if no arguments are given, a list of the recognized commands. 

Terminate an active spooling daemon on the local host immediately 
and then disable printing (preventing new daemons from being 
started by ipr) for the specified printers. 

Remove any temporary files data files and control files that cannot 
be printed (that is they do not form a complete printer job) from the 
specified printer queues on the local machine 
Turn the specified printer queues off. This prevents new printer jobs 
from being entered into the queue by ipr. 
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Ic down 


all - printer mess age ... 




all -- printer 


restart all ■ pri n 


status No all ■ p 
stop all ■ pri nt e 


topq pri 
up all 


[ j obnnm ... ] [user ... ] 


T urn the specified printer queue off, disable printing, and put message 
in the printer status file. T he message doesn't need to be quoted; the 
remaining arguments are treated like echo(l). T his is usually used to 
take a printer down and let others know why ipq(l) indicates the 
printer isdown and print the status message. 

Enable spooling on the local queue for the listed printers Thisallows 
ipr(l) to put new jobs in the spool queue. 

Exit from ipc. 

Attempt to start a new printer daemon. This isuseful when some 
abnormal condition causes the daemon to die unexpectedly leaving 
jobs in the queue. ipq reports that there is no daemon present when 
this condition occurs. If the user is the super-user, try to abort the 
current daemon first (that is, kill and restart a stuck daemon). 

Enable printing and start a spooling daemon for the listed printers. 

D isplay the status of daemons and queues on the local machine 
Stop a spooling daemon after the current job completes and disable 
printing. 

Place the jobs in the order listed at the top of the printer queue 
Enable everything and start anew printer daemon. U ndoes the effects 
of down. 


FILES 

/etc/printcap printer description file 

/var/spooi/* spool directories 

/var/spooi/*/iock lock filefor queue control 

SEE ALSO 

lpd(8), lpr(l), lpq(l), lprm(l), printcap(5) 

DIAGNOSTICS 

?Ambiguous command Abbreviation matches more than one command. 

?Invalid command N 0 match WasfOUnd. 

?priviieged command C ommand can be executed by root only. 

HISTORY 

Theipc command appeared in BSD 4.2. 

BSD 4.2,16 M arch 1991 


lpd 

ipd— Line printer spooler daemon. 

SYNOPSIS 

lpd [-1] [port#] 

DESCRIPTION 

ipd istheline printer daemon (spool area handler) and is usually invoked at boot time from the rc(8) file It makes a single 
pass through the pnintcap(5) file to find out about the existing printers and prints any files left after a crash. It then uses the 
system calls iisten(2) and accept(2) to receive requests to print filesin the queue, transfer files to the spooling area, display 
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the queue or remove jobs from the queue In each case, it forks a child to handle the request so the parent can continue to 
listen for more requests. 

Available options: 

-l The -i flag causes ipd to log valid requests received from the network. This can be useful for 

debugging purposes 

port# The Internet port number used to rendezvous with other processes is usually obtained with 

getservbyname(3) but can be changed with thepor t # argument. 

Access control isprovided by two means First, all requests must come from oneofthemachineslisted in the file/etc/ 
hosts.equtv or /etc/hosts.ipd. Second, if the rs capability isspecified in the prtntcap entry for the printer being accessed, 
ipr requests are only honored for those users with accounts on the machine with the printer. 

Thefileminfree in each spool directory containsthe number of disk blocks to leave free so that the line printer queue won't 
completely fill the disk. Theminfreefilecan be edited with your favorite text editor. 

The daemon begins processing files after it hassuccessfully sdt the lock for exclusive access (described later) and scans the 
spool directory for files beginning with cf. Lines in each cf file specify files to be printed or non-printing actions to be 
performed. Each such line begins with a key character to specify what to do with the remainder of the line: 
j Job name String to be used for the job name on the burst page, 

c C lassification. String to be used for the classification line on the burst page. 

l Literal. The line contains identification info from the password file and causes the banner page 

to be printed. 

t Title. Stringto beused as the title for pr(l). 

h Hostname Name of the machine where ipr wasinvoked. 

p Person. Login name of the person who invoked ipr. This is used to verify ownership by lprm. 

m Send mail to the specified user when the current print job completes 

f Formatted file. N ame of a file to print which is already formatted. 

1 Like f but passes control characters and does not make page breaks 

p Nameof afileto print using pr{l) as a filter. 

t T raff file. Thefilecontainstroff(l) output (cat phototypesetter commands), 

n Ditrofffile. Thefilecontainsdeviceindependenttroff output, 

r DVI file. The file contains Tex I output DVI format from Standford. 

g G raph fi le. T he fi le contai ns data produced by piot(3). 

c Cifplotfile Thefilecontainsdata produced bycifpiot. 

v Thefilecontainsa raster image 

r Thefilecontainstextdatawith FORTRAN carriage control characters 

1 T raff font R. N ame of the font fi le to use instead of the default. 

2 T raff font I. N ameofthefontfileto use instead ofthedefault. 

3 T raff font B. Nameof the font file to use instead ofthedefault. 

4 T raff font S. N ame of the font file to use i nstead of the default. 

w Width. Changes the page width (in characters) used by pr(l) and the text filters, 

i Indent. The number of characters to indent the output by (in ASCII), 

u Unlink. Nameof fileto removeupon completion of printing. 

n Filename The name of the file that is being printed or a blank for the standard input (when ipr 

is invoked in a pipeline). 

If a file cannot be opened, a message is logged via sysiog(3) using the log lpr facility, ipd tries up to 20 times to reopen a file 
it expects to be there after which it skips thefileto be printed. 
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ipd usesfiock(2) to provide exclusive access to the lock file and to prevent multiple daemons from becoming active 
simultaneously. If the daemon should be killed or die unexpectedly, the lock file need not be removed. The lock file is kept 
in a readable ASCI I form and contains two lines. Thefirst is the process ID of the daemon and the second is the control 
filename of the current job being printed. The second line is updated to reflect the current status of ipd for the programs 
lpq(l) and lprm(l). 

FILES 

/etc/printcap 
/var/spool/* 

/var/spool/*/minfree 
/dev/lp* 

/dev/printer 
/etc/hosts.equiv 
/etc/hosts.Ipd 

SEE ALSO 

lpc(8), pac(l), lpr(l), lpq(l), lprm(l), syslog(3), printcap(5) 

4.2 BSD Line Printer Spooler M anual 

HISTORY 

An ipd daemon appeared inversion 6, AT&T UN IX. 

BSD 4.2,16 Wardn 1991 


Printer description file 

Spool directories 

M ini mum free space to leave 

Line printer devices 

Socket for local requests 

Lists machine names allowed printer access 

Lists machine names allowed printer access but not under same administrative control 


MAKEDEV 

makedev- Creates and maintains filesystem device entries. 

SYNOPSIS 

MAKEDEV [ -vcdnhV ] device or device-group names 

DESCRIPTION 

makedev is used to maintain the special filesystem entriesfound in /dev. It creates, or optionally removes, one or more device 
entries. The names and device numbersare defined in thedevinfo file (q.v.); site-specific configuration isfound in thefile 
makedev. cfg. makedev itself hasno knowledge of device information. 

OPTIONS 

-v Verbose mode; print out exactly what's being done 

-c Create; create the specified devices (default). 

-d Delete; remove the specified devices instead of creating them. 

-n Do nothing; only print whatwould bedone Implies -v as well. 

- h P ri nt a usage message. 

-v Print the version string. 

T hefollowing targets are special: 

update Run MAKEDEvin updatemode. This reads the list of devicescurrently availablefrom 

/proc/devices and updates all entries in / dev to match the device numbers found there. 
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Run makedev to create local devices This option is obsolete and just prints a warning message. 
U se devinfo. local and makedev. cfg to achieve the same results 


FILES 

/etc/devinfo 

/usr/local/etc/devinfo.local 
/etc/devinfo.local 
/etc/makedev.cfg 
MAKEDEV.cache 
/proc/devices 


Device information 

Local device information 

Alternate location for local device information 

Configuration file 

Cached data for update 

The kernel's list of current devices 


AUTHOR 

David A. H olland (dhoiiand@husc.harvard.edu). Based on the older makedev shell script written by N ick H olloway. Addi¬ 
tional ideas were contributed by Rik Faith. 

NOTES 

TheLALR(l) parser generator used to build makedev.c from makedev.syn isa commercial product. You won't beableto do a 
complete rebuild unless you have it. 

SEE ALSO 

devinfo(5), makedev.cfg(5) 

Version 1.5, March 1995 
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SYNOPSIS 


cd 

cd 

cd 


./MAKEDEV -V 
./MAKEDEV [ -n 
./MAKEDEV [ -n 


[ -v ] update 
[ -v ] [ -d ] devi ce ... 


DESCRIPTION 

makedev isa script that creates thedevicesin /dev used to interface with drivers in thekernel. 

Note that programs giving the error enoent: no such file or directory usually meansthatthedevicefileismissing, whereas 
enodev: No such device usually means the kernel does not have the driver configured or loaded. 

OPTIONS 

-v Print out version (actually RCS version information) and exit. 

-n Do not actually update the devices; just print the actions that would beperformed. 

-d Delete the devices The main use for thisflag is by makedev itself. 

-v Beverbose. Print out the actions as they are performed. This is the same output as produced by -n. 


CUSTOMIZATION 

Because there iscurrently no standardization in what names are used for system users and groups, it is possible that you 
might need to modify makedev to reflect your site's settings N ear the top of thefile isa mapping from device type to user, 
group, and permissions (For example, all CD-ROM devices are sdt from the$cdrom variable.) If you want to change the 
defaults this is the section to edit. 
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DEVICES 


General Options 


update 

generic 

%std 

Virtual T erminals 

This only works on kerndsthat have/proc/interrupts (introduced during 1.1.x). Thisfile is 
scanned to see what devices are currently configured into the kernd, and this iscompared with 
the previous settings stored in the file called devices. Devices that are new since then orhavea 
different major number are created, and those that are no longer configured are ddeted. 

C reate a generic subset of devices T his isthe standard devices plusfloppy drives, various hard 
drives pseudo-terminals, console devices, basic serial devices, busmice, and printer ports 
Standard devices These are mem, accessto physical memory; kmem, access to kernel virtual 
memory; nun, null device (infinite sink); port, accessto I/O ports zero, null byte source 
(infinite source); core, symiink to /proc/kcore (for kernel debugging); full, always returns 
enospace on write; ram, ramdisk; tty, to access the controlling tty of a process 

This simply runs makedev. local. This is a script that can create any local devices 

console 

Thiscreatesthedevices associated with theconsole This isthe virtual terminals tty*, where* 
can be from e though 63. The device ttyo is the currently active vt and is also known as console 
For each vt, there are two devices vcs* and vcsax, which are used to generate screen-dumps of 
thevt (thevcsx isjuSt thetext and vcsax includestheattributes). 

Serial D e/ices 

ttyS{0..63} 

Serial ports and corresponding dial-out device. For device ttysx, there isalsothedevicecua*, 
which is used to dial out with. T his can avoid the need for cooperative locks in simple 
situations 

cyclades 

Dial-in and dial-out devices for the cyclades intelligent I/O serial card. The dial in device is 
ttyCx and the corresponding dial-out device is cubx. By default, devices for 7 lines are created, 
but this can be changed to 15 by removing the comment. 

Pseudo T erminals 

pty[p-s] 

Each possible argument will create a bank of 16 master and slave pairs. The current kernel (1.2) 
is limited to 64 such pairs The master pseudo-terminalsarepty[p-s][0-9a-f] and the slaves are 

tty[p-s][0 - 9a-f]. 

Parallel Ports 

ip 

Standard parallel ports. The devices are created lpo, ipi, and ip2. These correspond to ports at 
0x3bc, 0x378, and 0x278. Hence, on some machines, the first printer port may actually beipi. 

par 

Alternative to ip. Ports are named par* instead of ipx. 

BusM ice 

busmice 

The various bus mice devices Thiscreatesthefollowing devices logimouse (Logitech bus 
mouse), psmouse (PS/2-style mouse), msmouse (M icrosoft Inport bus mouse), atimouse (ATI XL 
bus mouse) and jmouse (J-mouse). 

Joystick Devices 

is 

J oystick. C reates j so and j si. 

Disk De/ices 

fd[0-7] 

Floppy disk devices. The device fd* is the device that autodetects the format, and the additional 
devices are fixed format (whose size is indicated in the name). The other devices are named as 
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fdxLn. The single letter L identifies the type of floppy disk (d =5.25" DD, h =5.25" H D, 
d =3.5" DD,h =3.5" H D, e =3.5" ED). T he number n represents the capacity of that format 
in KB. Thus the standard formats are fd*d36B, fdxhi200, fdxD720, fdxHi440, and fdxE2880. 

For more information, see Alain K naff's fdutiis pack-age. 

Devices fd 0 * through fd3* are floppy disks on thefirst controller, and devices fd4* through fd7* 
are floppy disks on the second controller. 

hd [ a - d] AT hard disks. The device hdx providesaccesstothewholedisk, with the partitions being 

hdx [ 0 - 20 ]. Thefour primary partitions are hdx i through hdx 4 , with the logical partitions being 
numbered from hdx 5 though hdx 20 . (A primary partition can be made into an extended 
partition, which can hold four logical partitions). By default, only the devices for four logical 
partitions are made. The others can be made by uncommenting them. 

D rives hda and hdb are the two on thefirst controller. If using the new IDE driver (rather than 
the old H D driver), then hdc and hdd are the two drives on the secondary controller. These 
de/ices can also be used to access ID E C D -RO M s if using the new ID E driver, 
xd [ a - d ] XT hard disks. Partitions are the same asID E disks. 

sd [ a - h] SCSI hard disks. The partitions aresimilar to the ID E disks, but there is a limit of 11 logical 

partitions (sdx5 through sdx 15). Thisisto allow 8 SCSI disks. 

loop Loopback disk devices These allow you to use a regular file as a block device This means that 

images of filesystems can be mounted and used as normal. T his creates 8 devices ioop0 through 

100p7. 


Tape Devices 


St[0-7] 

CD-ROM Devices 

SCSI tapes This creates the rewinding tape device stx and the non-ravinding tape device nstx. 
QIC-80 tapes. The devices created arermts, ™ti6, tape-d, and tape-reset. 

Floppy driver tapes (QIC-117). There are four methods of access depending on thefloppy tape 
drive. For each of the access methods 0,1, 2, and 3, the devices rftx (rewinding) and nrftx 
(non-rewinding) are created. For compatibility, devices ftape and nftape aresymlinksto rft@ 
and nrtt0. 

scd[0-7] 

SCSI CD players. 

sonycd 

SonyCDU-31A CD player. 

mod 

M itsumi C D player. 

cdu535 

Sony CDU-535 CD player. 

lmscd 

LM S/PhilipsCD player. 

sbpcd{,1,2,3} 

SoundBlaster CD player. The kernel is capable of supporting 16 CD-ROMs, each of which is 
accessed assbpcd[0-9a-f]. These are assigned in groups of four to each controller, sbpcd isa 
symlinkto sbpcd0. 

Scanner 

logiscan 

Logitech ScanM an32 and ScanM an 256. 

m105scan 

M ustek M 105 H andscanner. 

ac4096 

Audio 

A4Tek Color FI andscanner. 


audio This creates the audio devices used by the sound driver. These include mixer, sequencer, dsp, 

and audio. 

pcaudio D evicesfor the PC Speaker sound driver. T hese are pcmixer, pxsp, and pcaudio. 
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M isoellaneous 
sg 


fd 




helloworld 

N etwork devices 


Generic SCSI devices The devices created aresgo through sg7. These allow arbitrary commands 
to be sent to any SCSI device This allows for querying information about the device or 
controlling SCSI devices that are not one of disk, tape, or CD-ROM (for example, a scanner or 
writable CD-ROM). 

To allow an arbitrary program to be fed input from file descriptor*, use/dev/fd/x as the 
filename. This also creates BR/dev/stdin, BR/dev/stdout, and BR/dev/stderr. (Note that these are 
justsymlinksinto /proc/seif/fd.) 

Devicesfand symlinks) needed by the IBCS2 emulation. 

D evicesfor power management. 

Driver for DCF-77 radio clock. 

Kernel modules demonstration device See the modules source. 

Linux used to havedevicesin /dev for controlling network devices, but that is no longer the 
case To see what network devices are known by the kernel, look at /proc/net/dev. 


SEE ALSO 

Linux Allocated Devices, maintained by H. Peter Anvin (peter.Anvin@iinux.org) 

AUTHOR 

N ick FI olloway 

Linux, 14 August 1994 


mke2fs 

mke2fs—Create a Linux second extended filesystem. 

SYNOPSIS 

mke2fs [ -c ] -1 filename ] [ -b block-size ] [ -f fragment-size ] 

[ -i bytes-per-inode ] [ -m reserved - bl ocks - percentage ] [ -q ][-v ][-S ] 
devi ce [ bl ocks- count ] 


DESCRIPTION 

mke 2 fs is used to create a Linux second extended filesystem on a device (usually a disk partition), device isthespecial file 
corresponding to the de/ice (such as /dev/hdxx). bi ocks-count isthe number of blockson the device. If omitted, mke2ts 
autom ati cal ly fi gures the fi lesystem si ze. 


Specify thesize of blocks in bytes 

Check the device for bad blocks before creating the filesystem using a fast read-only 
test. 

Specify the size of fragments i n bytes. 

Specify the bytesdnode ratio. mke2ts creates an inode for every bytes -per- i node bytes 
of space on the disk. This value defaults to 4096 bytes bytes-per-i node must be at 
least 1024. 

Read the bad blocks list from t i i ename. 

Specify the percentage of reserved blocks for the super-user. This value defaults to 5 
percent. 

Quiet execution. Useful if mke2fs is run in a script. 

Verbose execution. 
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•s W rite superblock and group descriptors only. This is useful if all the superblock and 

backup superblocks are corrupted and a last-ditch recovery method isdesired. It 
causes mke 2 fs to reinitialize the superblock and group descriptors while not touching 
the inode table and the block and inode bitmaps. The e2fsck program should be run 
immediately after this option is used, and there is no guarantee that any data will be 
salvageable 


AUTHOR 

This version of mke2fs has been written by Theodore T'so (tytso@mit.edu). 

BUGS 

mke 2 ts accepts the -f option but currently ignores it because the second extended filesystem does not support fragments yet. 

T here may be some other bugs Please report them to the author. 

AVAILABILITY 

mke2fs is avail able for anonymous FTP from ftp.ibp.fr and tsx-11.mit.edu in /pub/linux/packages/ext2fs. 

SEE ALSO 

badblocks(8), dumpe2fs(8), e2fsck{8), tune2fs(8) 

Verson 0.5b, N ovember 1994 


mkfs 

mkfs— Build a Linux filesystem. 

SYNOPSIS 

DESCRIPTION 

mkfs is used to build a Linux filesystem on a device usually a hard disk partition, m esys is either the device name (such as/ 
dev/hdai, /dev/sdb2) or the mount point (such as/, /usr, /home) for the filesystem, blocks isthe number of blocks to be used 
for the filesystem. 

The exit code returned by mkfs iso on success and i on failure. 

In actuality, mkfs is simply a front end for the various filesystem builders (mkfs.fstype) available under Linux. The filesystem- 
specific builder issearched for in /etc/fs first, then in /etc, and finally in thedirectories I i sted in the path environment 
variable Please see the filesystem-specific builder manual pages for further details 

OPTIONS 

-v Produce verbose output, including all filesystem-specific commands that are executed. 

Specifying this option more than once inhibits execution of any filesystem-specific commands 
This is really only useful fortesting. 

-tfstype Specifies the type of filesystem to be built. If not specified, the type is deduced by searching for 

fi i esys in /etc/fstab and using the corresponding entry. If thetype cannot be deduced, the 
default filesystem type (currently minix) is used. 

fs-options Filesystem-specific options to be passed to the real filesystem builder. Although not guaranteed, 

thefollowing options are supported by most filesystem builders 
-c Check the device for bad blocks before building thefilesystem. 

- If i I e n a me Read the bad blocks list from f i I ename. 

-v Produce verbose output. 
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BUGS 

All generic options must precede and not be combined with filesystem-specific options Some filesystem-specific programs do 
not support the -v (verbose) option nor return meaningful exit codes Also, some filesystem-specific programsdo not 
automatically detect the device size and require the blocks parameter to be specified. 

AUTHORS 

David Engel (david@ods.com), Fred N . van Kempen (waitie@uwait.rn.mugnet.org), and Ron Sommeling (sommei@sci.kun.ni). 
The manual page was shamelessly adapted from Remy Card's version fortheext 2 filesystem. 

SEE ALSO 

fsck(8), mkfs.minix(8), mkfs.ext(8), mkfs.ext2(8), mkfs.xiafs(8) 

Verson 1.9,Junel995 
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mkfs — M akeaLinux M IN IX filesystem. 

SYNOPSIS 

mkfs [ -c ] [ -nn a me I e n g t h | [ -i i nodecount ] device size- i n- bl ocks 
mkfs [ -1 filename ] device s i ze-i n- bl oc|| 

DESCRIPTION 

mkfs creates a Linux M IN IX filesystem on a device (usually a disk partition). 

The device is usually of the following form: 

/dev/hda[1-8] 

/dev/hdb[1-8] 

/dev/sda[1-8] 

/dev/sdb[1-8] 

The s i ze- i n- bi ocks parameter isthedesired sizeofthefilesystem in blocks This information can be determined from the 
fdisk(8) program. 0 nly block counts strictly greater than 10 and strictly less than 65,536 are allowed. 

OPTIONS 

-c Check the device for bad blocksbeforecreatingthefilesystem. If any arefound, thecountis 

printed. 

- nn a me i ength Specify themaximum length of filenames No space is all owed between the -n and the 

name i ength. Currently, theonly allowable values are 14 and 30.30 isthedefault. 

-i i nodecount Specify the number of inodes for the filesystem. 

-1 f i 1 ename Read the bad blocks list from f i 1 ename. The file has one bad block number per line. The count 

of bad blocks read is printed. 

EXIT CODES 

The exit code returned by mkfs.minix is one of the following: 

0 N 0 errors 

8 Operational error 

i6 U sage or syntax error 

SEE ALSO 

fsck(8), mkefs(8), efsck(8), reboot(8) 
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AUTHOR 

LinusTorvalds (torvaids@cs.heisinki.fi). Error code values by Rik Faith (faith@cs.unc.edu). I node request feature by Scott 
Heavner (sdh@po.cwru.edu). Support for the filesystem valid flag by Dr. Wettstein (greg%wind. uucp@piatns.nodak.edu). 

Check to prevent mkfs of mounted filesystem and boot sector clearing by Daniel Quinlan (quinian@yggdrasii.com). 

Linux0.99,10 January 1994 
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mkiost+found— C reate a lost+found directory on amounted Linux second extended filesystem. 

SYNOPSIS 

mklost+found 

DESCRIPTION 

mkiost+found is used to create a lost+found directory in the current working directory on a Linux second extended filesystem, 
mkiost+found pre- allocates disk blocks to the directory to make it usable by e2f sck. 

OPTIONS 

There are none 

AUTHOR 

mkiost+found was written by Remy Card (card@masi.ibp.fr), the developer and maintainer of theext 2 fs. 

BUGS 

There are none :-) 

AVAILABILITY 

mklost+found is available for anonymous FT P from ftp.ibp.fr and tsx-11.mit.edu in /pubAlnux/packages/ext2fs. 

SEE ALSO 

e2fsck(8), mke2fs(8) 

Veraon 0.5b, N ovember 1994 


mkswap 

mkswap— Set up a Linux swap area. 

SYNOPSIS 

DESCRIPTION 

mkswap sets up a Linux swap area on a de/ice or in a file 
The device is usually of the following form: 

/dev/hda[1-8] 

/dev/hdb[1-8] 

/dev/sda[1-8] 

/dev/sdb[1-8] 
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Thes i ze-i n- bi ocks parameter isthedesired size of thefilesystem in blocks This information isdetermined automatically by 
mkswap if it isomitted. Block counts are rounded down so that the total size is an integer multiple of the machine's page size 
0 nly block counts in the range mincount. .maxcount are allowed. If the block count exceeds the maxcount, it is truncated to 
that value and a warning message is issued. 

The mincount and maxcount values for a a/vap area are 
mincount =10 * page_size /1024 
MAXCOUNT =(page_size-10)*8 *page_size /1024 
For example, on a machine with 4KB pages (such asx86), wegdt 
mincount = 10 * 4096 / 1024 =40 
maxcount = (4096 - 10) * 8 * 4096 / 1024 = 130752 

As each block islKB.theswap area in this example could have a size that is anywhere in the range from 40KB to 
127.6875M B. 

If you don't know the page size that your machine uses, you may be able to look it up with cat /proc/cpuinfo. 

The reason for the limit on maxcount isthat a single page is used to hold the swap bitmap at the start of the swap area, where 
each bit represents a single page. The reason for the -10, is that the signature is swap - space - 10 characters. 

To sdt up a swap file it is necessary to create that file before running mkswap. A sequence of commands similar to the 
following is reasonable for this purpose: 

# dd if=/dev/zero of=swapfile bs=1024 count=8192 

# mkswap swapfile 8192 

# sync 

# swapon swapfile 

N otethat a swap file must not contain any holes (so using cp(l) to create thefile is not acceptable). 

OPTIONS 

-c Check the device for bad blocks before creating the filesystem. If any are found, thecount 

is printed. This option is meant to be used for swap partitions only and should not be 
used for regular files! To make sure that regular files do not contain bad blocks, the 
partition that contains the regular file should have been created with mkfs -c. 

SEE ALSO 

fsck(8), mkfs{8), fdisk(8) 

AUTHOR 

LinUST orvalds (torvalds@cs .helsinki.fi) 

Linux 1.0, 8 February 1995 


mount,umount 

mount, umount- M ount and dismount filesystems. 

SYNOPSIS 

mount [-afrwuvn] [-t vfstype] 
mount [-frwuvn] [-0 remount [,...]] special | node 
mount [-frwun] [-t vfstype] [-0 options] special ] node 
umount [-an] ]-t vfstype] 
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The mount command calls the mount(2) system call to prepare and graft a special device onto the filesystem tree at the point 
node. If either s pec i ai or node are not provided, the appropriate information istaken from the fstab(5) file. T hespecial 
keyword none can be used instead of a path or node specification. This isuseful when mounting the proc filesystem. 

The system maintains a list of currently mounted filesystems. If no arguments are given to mount, this list is printed. 

0 ptions available for the mount command: 




defaults 


noauto 


noexec 


nouser 

remount 




C auses everything to be done except for the actual system call; if it's not obvious, this 
"fakes" mounting the filesystem. Thisoption isuseful in conjunction with the -v flag to 
determine what the mount command istrying to do. 

0 ptions are specified with a -o flag followed by a comma-separated string of options. 

N ote that many of these optionsare only useful when they appear in the /etc/fstab file. 
Thefollowingoptionsapply to anyfilesystem that isbeing mounted: 

All I/O to thefilesystem should be done asynchronously. 

Can be mounted with the - a option. 

Use default options: rw, suid, dev, exec, auto, nouser, and async. 

Interpret character or block special devices on thefilesystem. 

Permit execution of binaries. 

Can only be mounted explicitly (that is, the -a option does not cause the filesystem to 
be mounted). 

D o not i nterpret character or block sped al devices on the filesystem. T his option is 
useful for a server that has filesystems containing special devices for architectures other 
than its own. 

Do not allow execution of any binaries on the mounted filesystem. Thisoption isuseful 
for a server that has filesystems containing binariesfor architectures other than its own. 
Do not allow set-user-identifier or set-group-identifier bits to take effect. 

Forbid an ordinary (that is, non-root) user to mountthefilesystem. 

Attempt to remount an already-mounted filesystem. This is commonly used to change 
the mount flags for a filesystem, especially to makea read-only filesystem writable 
M ountthefilesystem read-only. 

M ount thefilesystem read-write. 

Allow set-user-identifier or set-group-identifier bits to take effect. 

All I/O to thefilesystem should be done synchronously. 

Allow an ordinary user to mount thefilesystem. 0 rdinary users always have the 
following options activated: noexec, nosuid, and nodev (unless overridden by the super- 
user by using, for example, thefollowing option line user,exec,dev,suid. 


Thefollowing optionsapply only to certain filesystems: 


normal 




Forthehpfs filesystem, specify case as lower or asis. 

Tells the ext2 filesystem kernel code to do some more checks while the filesystem is 
mounted. Currently (0.99.15), thefollowing values can be specified with thisoption: 

N o extra check is performed by the kernel code 

Theinodesand blocks bitmaps are checked when thefilesystem is mounted (thisisthe 
default). 

In addition to the normal checks, block deallocation checks that the block to free is in 
the data zone 

For the msdos filesystem, three different levels of specificity can be chosen: 



Part VIII: A dmi ni strati on and Pri vileged C ommands 


normal 




Uppercase and lowercase are accepted and equivalent, long name parts are truncated (for 
example, veriongname.foobar becomes veryiong.foo), leading and embedded spaces are 
accepted in each name part (nameand extension). 

Like relaxed but many special characters (*, ?, <, spaces, and soon) arerqected. This is 
the default. 

Like normal, but names may not contain long parts and special characters that are 
sometimes used on Linux but are not accepted by MS-DOS are rq'ected (+, =, spaces, 
and so on). 

Forthemsdos, hpfs, and iso9660 filesystems, specify file conversion asbinary, text, or 
auto. Theiso9660 filesystem also allows value to bemtext. 

Themsdos filesystem can perform crlf<->nl (M S-DOS text format to UN IX text 
format) conversion in the kernel. The following conversion modes are available: 

N o translation is performed. This isthedefault. 
crlf<->nl translation is performed on all files 

crlf<->nl translation is performed on all files that don't havea well-known binary 
extension. The list of known extensions can be found at the beginning of 
fs/msdos/misc.c (aSOf 09913r, the list isexe, com, bin, app, sys, drv, ovl, ovr, obj, lib, 
dll, pit, arc, zip, lha, lzh, zoo, tar, z, arj, tz, taz, tzp, tpz, gif, bmp, tif, gl, jpg, pcx, 
tfm, vf, gf, pk, pxl, and dvi). 


Programs that do computed lseeks won't like in-kernel text conversion. 

For filesystems mounted in binary mode a conversion tool (fromdos/todos) isavailable 


block=val lie 
bsdgroups 


debug 


continue 

remount, ro 


fat=v a I ue 

gid=v a I ue 
B grpid 

map=v a I ue 


nocheck 


For the iso9660 filesystem, set the block size 
See grpid. 

Fortheiso9660 filesystem, set the cruft flag to y. This option is available because there 
are buggy premastering programs out there that leavejunk in thetop byte of thefile 
size. This option clears the top byte but restricts filesto 16M B maximum in the process. 
Forthemsdos filesystem, turn on the debug flag. A version string and a list of filesystem 
parameters is printed. (T hese data are also printed if the parameters appear to be 
inconsistent.) 

Fortheext 2 fs filesystem, cause the kernel code to display thefilesystem parameters 
when thefilesystem is mounted. 

Fortheext 2 fs filesystem, specify the error behavior: 

N o special action istaken on errors (except marking thefilesystem as erroneous). Thisis 
the default. 

Thefilesystem isremounted read only, and subsequent writes are refused. 

When an error is detected, the system panics. 

For the msdos filesystem, specify either a 12-bit fat or a 16-bit fat. This overrides the 
automatic FAT type detection routine Use with caution! 

Forthemsdos and hpfs filesystems, give every file a gid equal to vai ue. 

C auses the ext2f s to usetheBSD behavior when creating files: Files are created with the 
group ID of their parent directory. 

Fortheiso9660 filesystem, specify mapping as off or normal. In general, non-Rock 
Ridge discs have all the filenames in uppercase, and all thefilenameshavea ;i 
appended. The map option stripsthe ;i and makesthe name lowercase (See also 

norock.) 

For the ext2f s, turns off checking (see check=none). 

C auses the ext2fs to use the System V behavior when creating files Files are created 
with the group ID of the creating process unless the setgid bit is set on the parent 
directory. T his isthe default for all Linux filesystems 





mount, unmount 


norock 


sysvgroups 


umask=val ue 


Normal iso960o filenames appear in a 8.3 format (that is, D 0 S-like restrictionson 
filename length), and in addition, all characters are in uppercase. Also there isno field 
for file ownership, protection, number of links, provision for block/character devices, 
and so on. 

Rock Ridge is an extension to iso9660 that provides all of these U N IX-like features. 
Basically, there are extensions to each directory record that supply all of the additional 
information, and when Rock Ridgeisin use, thefilesystem is indistinguishable from a 
normal UNIX filesystem (except that it isread only, of course). 

The norock switch disables the use of Rock Ridge extensions, even if available. (See also 
map.) 

Forthemsdos filesystem, turn on the quiet flag. Attempts to chown or chmod files do not 
yield errors, although they fail. Use with caution! 

For the ext 2 filesystem, use an alternate superblock located at block vai ue . vai ue is 
numbered in 1024-byte blocks An ext 2 filesystem usually has backups of the superblock 
at blocks 1, 8193,16385, and so on. 

Seenogrpid. 

Forthemsdos and hpts filesystems, give every file a uid equal to vai ue. 

Forthemsdos and hpts filesystems, give every file a umask of vai ue. The radix defaults to 
octal. 


The full set of options applied is determined by first extracting the optionsfor the filesystem from the f stab table, then 
applying any options specified by the -o argument, and finally applying the -r or -w option. 

If the msdos filesystem detects an inconsistency, it reports an error and sdts thefilesystem to read only. Thefilesystem can be 
made writable again by remounting it. 

-r Thefilesystem object isto be mounted read only. 

-t vf stype The argument following the -t isused to indicate the filesystem type. Thefilesystem 

types that are currently supported are listed in linux/fs/fiiesystems.c: minux, ext, ext 2 , 
xiafs, msdos, hpfs, proc, nfs, iso9660, sysv, Xenix, coherent. N Ote that that last three are 
equivalent and that xenix and coherent will be removed at some point in the future; use 
sysv instead. 

The type minix is the default. If no -t option is given, or if the auto type is specified, the 
superblock isprobed for thefilesystem type(minix, ext, ext 2 , and xia are supported). If 
thisprobefailsand /proc/fiiesystems exists, then all the filesystems listed are tried, 
except for those labeled nodev (such as proc and nts). 

N ote that the auto type may be useful for user-mounted floppies. For example, the mount 
command mounts all filesystems except those of type msdos and ext: 
mount -a -t nomsdos.ext 

-v Verbose mode. 

-w T he filesystem object isto be read and write. 

-n M ount without writing in /etc/mtab. 

umount removes the sped ai device grafted at point node from thefilesystem tree. 

Optionsfor the umount command: 

-a All of the filesystems described in /etc/mtab are unmounted. 

-t vf stype Isused to indicate the actions should only betaken on filesystems of the specified type. 

M orethan one type may be specified in a comma-separated list. The list of filesystem 
types can be prefixed with no to specify thefilesystem types on which no action should 
betaken. (See example for the mount command.) 
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FILES 

/etc/fstab 
/etc/mtab' 

/etc/mtab.tmp 

SEE ALSO 

mount(2), umount(2), fstab(5), swapon(8) 

BUGS 

It ispossiblefor a corrupted filesystem to cause a crash. 

Some Linux filesystems don't support -o synchronous (the ext2fs does support synchronous updates (a la BSD) when 
mounted with the sync option). 

The -o remount may not be able to change mount parameters (all ext2fs parameters, except sb, are changeable with a 
remount, for example but you can't change gid or mask for thedosfs). 

HISTORY 

A mount command appeared in Version 6, AT&T UNIX. 

AUTHORS AND CONTRIBUTORS 

The Linux mount command has a long and continuing history. Thefollowing major releases are noted with the name of the 
primary modifier: 

0.97.3: D oug Q uale (quale@saavik. cs.wise.edu) 

0.98.5: H .J. Lu (hlu@eecs.wsu.edu) 

0.99.2: Rick Sladkey (jrs@worid.std.com) 

0.99.6: Rick Sladkey (jrs@worid.std.com) 

0.99.10: Stephen Tweedie (sct@dcs.ed.ac.uk) 

0.99.14: Rick Sladkey (jrs@worid.std.com) 

(Filesystem-specific information added to man page on 27 November 1993 by Rik Faith with a lot of information and text 
from thefollowing filesystem authors: Werner Almesberger, Eric Youngdale and RemyCard.) 

Linux 1.1, 8 February 1995 


Filesystem table 
Lock file 
Temporary file 



mountd 

mountd— NFS mount daemon. 

SYNOPSIS 

/usr/etc/rpc.mountd [\-f\--exports-file\][\-dhnprv\] 
[\--debug!][\--exports-file=file\] [\--help!] 

[!--allow-non-root!][!--re-export!][!--version!] 

DESCRIPTION 

The mountd program isan N FS mount daemon. 

OPTIONS 




>-file 


This option specifies the exports file, listing thedients that this server is prepared to 
serve and parameters to apply to each such mount (see exports(5)). By default, exports 
are read from /etc/exports. 



named-xfer 


■d Or - -debug 
-hor - -help 
-n Or - -allow-non-root 


-p Or - -promiscuous 
-r Or --re-export 


Log each transaction verbosely to the sysiog. 

Provide a short help summary. 

Allow incoming mount requests to be honored even if they do not originate from 
reserved IP ports Someolder N FS client implementations require this Some newer 
NFS client implementations don't believe in reserved port checking. 

Puttheserver into promiscuous mode where it will serve any host on the network. 
Allow imported N FS filesystems to be exported. This can be used to turn a machine 
into an N FS multiplier. Caution should be used when reexporting loopback N FS 
mounts because reentering the mount point results in deadlock between the N FS client 
and the N FS server. 

Report the current version number of the program. 


SEE ALSO 

exports(5), nfsd(8), ugidd(8C) 


BUGS 

The current implementation (still) does not keep track of remote mounts. 


13 October 1993 


named-xfer 

named-xfer—Ancillary agent for inbound zone transfers. 

SYNOPSIS 

DESCRIPTION 

named-xfer isan ancillary program executed by named(8) to perform an inbound zonetransfer. It is rarely executed directly 

and only by system administrators who are trying to debug a zonetransfer problem. See RFCs 1033,1034, and 1035 for 

more information on the I nternet name-domain system. 

Options are 

-z Specifies the name of the zone to be transferred. 

-f Specifies the name of the fileinto which the zone should be dumped when it is received 

from the primary server. 

-s Specifies the serial number of the current copy of this zone. If theSOA RR you get from 

the primary server does not have a serial number higher than this, the transfer is aborted. 

-d Print debugging information. A number after the d determines the level of messages 

printed. 

-l Specifies a log file for debugging messages The default is system-dependent but is 

usually in /var/tmp or /usr/tmp. N ote that this only applies if -d isalso specified. 

-t Specifies a trace file that contains a protocol trace of the zone transfer. This is probably 

only of interest to people debugging thenameserver itself. 

-p Use a different port number. The default is the standard port number as returned by 

getservbyname(3) for service "domain". 

-s Perform a restricted transfer of only theSOA, N S records and glue A records for the 

zone. TheSOA record is not loaded by named but is used to determine when to verify 
the N S records Seethe stubs directive in named(8) for more information. 
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Additional arguments are taken asnameserver addressesin so-called "dotted-quad" syntax only; no hostnames are allowed 
here At least one address must be specified. Any additional addresses are tried in order if the first one fails to transfer 
successfully. 

SEE ALSO 

named(8), resolver(3), resolver(5), hostname(7), RFC 882, RFC 883, RFC 973, RFC 974, RFC 1033, RFC 1034, RFC 
1035, RFC 1123, NameServer OperationsGuide for BIND 

26Junel993 


named 

named— I nternet domain nameserver. 

SYNOPSIS 

named [ -d debugl evel ][-p port# [/I ocal port #]][{-b> boot file ][-q ][-r ] 

DESCRIPTION 

named is the Internet domain nameserver. See RFCs 1033,1034, and 1035 for more information on the I nternet name- 
domain system. Without any arguments, named reads the default boot file/etc/named, boot, reads any initial data, and listens 
for queries. 

Options are 

-d Print debugging information. A number after the d determines the level of messages 

printed. 

-p U se nonstandard port numbers The default is the standard port number as returned by 

getservbyname(3) for service "domain". T he argument can specify two port numbers 
separated by a si ash (/), in which casethefirst port isthat used when contacting remote 
servers and the second one isthe service port bound by the local instance of named. This 
is used mostly for debugging purposes 

-b Use an alternate boot file This is optional and allows you to specify a file with a leading 

dash. 

-q T race all incoming queries if named has been compiled with qrylog defined. Note that 

thisoption isdeprecated in favor of the boot file directive options query-iog. 

-r T urns recursion off in the server. Answerscan comeonlyfrom local (primary or 

secondary) zones This can be used on root servers. Note that this option isdeprecated 
in favor of the boot file directive options no-recursion. 

Any additional argument is taken as the name of thebootfile If multiple boot files are specified, only the last is used. 

The boot file contains information about wherethenameserveristo get its initial data. Lines in theboot file cannot be 
continued on subsequent lines. The following isa small example; 



directory /usr/local/adm/named 
; type domain source host/file backup file 

primary Berkeley.EDU berkeley.edu.zone 
primary 32.128.IN-ADDR.ARPA ucbhosts.rev 

secondary CC.Berkeley.EDU 128.32.137.8 128.32.137.3 cc.zone.bak 
secondary 6.32.128.IN-ADDR.ARPA 128.32.137.8 128.32.137.3 cc.rev.bak 
primary 0.0.127.IN-ADDR.ARPA localhost.rev 



named 


forwarders 10.0.0.78 10.2.0.78 
limit transfers-in 10 
limit datasize 64M 

options forward-only query-log fake-iquery 

The directory line causes the server to change its working directory to the directory specified. This can be important for the 
correct processing of $include files in primary zonefiles. 

The cache line specifies that data in root.cache isto be placed in the backup cache 

Its main use isto specify data such as locations of root domain servers. This cache is not used during normal operation, but is 
used as "hints" to find the current root servers. T he fi le root. cache is in the same format as berkeiey. edu. zone. T here can be 
more than one cache file specified. The root, cache file should be retrieved periodically from ftp.rs.internic.net because it 
contains a list of root servers, and this list changes periodically. 

T he first sample primary line states that the file berkeiey. edu. zone contai ns authoritative data for the Berkeley. edu zone T he 
file berkeiey. edu. zone contains data in the master file format described in RFC 883. All domain names are relative to the 
origin, in thiscase Berkeiey.EDu (see below for a more detailed description). The second primary line states that thefile 
ucbhosts.rev contains authoritative data for the domain 32.i28.in-addr.arpa, which isused to translate addresses in network 
128.32 to hostnames. Each master file should begin with an SO A record for the zone (see below). 

Thefirst sample secondary line specifies that all authoritative data under cc.Berkeiey.EDu isto be transferred from the 
nameserver at 128.32.137.8. If thetransfer fails, it tries 128.32.137.3 and continues trying the addresses, up to ten, listed on 
this line. The secondary copy isalso authoritative for the specified domain. Thefirst non-dotted-quad addresson this line is 
taken asa filename in which to back up the transferred zone The nameserver loads the zone from this backup file if it exists 
when it boots, providing a complete copy even if the master servers are unreachable W henever a new copy of the domain is 
received by automatic zone transfer from oneof the master servers, thisfile is updated. If no filename is given, atemporary 
file is used and deleted after each successful zone transfer. T his is not recommended because it isa needless waste of 
bandwidth. The second sample secondary line states that the address-to-hostname mapping for the subnet 128.32.136 should 
be obtained from the same list of master servers as the previous zone. 

Theforwarders line specifiesthe addresses of sitewide servers that will accept recursive queries from other servers. If the boot 
file specifies one or more forwarders, then the server sends all queries for data not in the cache to the forwarders first. Each 
forwarder is asked in turn until an answer is returned or thelist is exhausted. If no answer is forthcoming from a forwarder, 
the server continues as it would have without the forwarders lineunlessit isin forward-only mode. Theforwarding facility is 
useful to cause a large sitewide cache to be generated on a master and to reduce traffic over links to outside servers It can also 
be used to allow servers to run that do not have direct access to the Internet but want to look up exterior names anyway. 

The slave line (deprecated) is allowed for backward compatibility. Its meaning is identical to options forward-only. 

The sortust line can be used to indicate networks that are to be preferred over other networks. Queries for host addresses 
from hosts on the same network as the server receive responses with local network addresses listed first, then addresses on the 
sort list, and then other addresses 

Thexfrnets directive (not shown) can be used to implement primitive access control. If thisdirective is given, your 
nameserver only answers zonetransfer requestsfrom hosts that are on networks listed in your xfrnets directives. This 
directive may also be given as tcpiist for compatibility with older, interim servers 

The include directive (not shown) can be used to process the contents of some other file as though they appeared in place of 
the include directive This is useful if you havea lot of zones or if you have logical groupingsof zones that are maintained by 
different people. The include directive takes oneargument, the name of the file whose contents are to be included. No 
quotes are necessary around the fi lename. 

Thebogusns directive (not shown) tells Bl N D that no queries are to be sent to the specified nameserver addresses (which are 
specified as dotted quads, not as domain names). This is useful when you know that some popular server has bad data in a 
zoneor cache, and you want to avoid contamination while the problem is being fixed. 

The limit directive can be used to change BIN D's internal limits, some of which (datasize, for example) are implemented 
by the system and others (such as transfers-in) by BIN D itself. The number following the limit name can be scaled by 
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postfixing a k, m, or g for kilobyte, megabytes, and gigabyte respectively, datasize's argument sets the process data size 
enforced by the kernel. Note that not all systems provide a call to implement this; on such systems, the use of thedatasize 
parameter of limit results in a warning message transfers -in's argument is the number of named -xfer subprocesses that 
BIND will spawn at any onetime, transfers-per-ns's argument is the maximum number of zone transfers to be simulta¬ 
neously initiated to any given remote nameserver. 

The options directive introduces a Boolean specifier that changes the behavior of BIN D. M ore than oneoption can be 
specified in a single directive. The currently defined options are as follows no-recursion, which causes Bl N D to answer with 
a referral rather than actual data whenever it receives a query for a name it is not authoritative for. Don't set this on a server 
that is listed in any host's resoiv.conf file, no-fetch-giue keeps BIN D from fetching missing glue when constructing the 
"additional data" section of aresponse; this can be used in conjunction with no-recursion to prevent BIN D's cache from ever 
growing in size or becoming corrupted, query-log causes all queries to be logged via sysiog(3). T his is a lot of data; don't 
turn it on lightly, forward-only causes the server to query only its forwarders. Thisoption is usually used on a machinethat 
wants to run a server but for physical or administrative reasons cannot be given access to the Internet, fake-iquery tells 
BIND to send back a useless and bogus reply to "inverse queries" rather than respond with an error. This is helpful if you 
have a lot of microcomputers or SunO S hosts or both. 

The max-fetch directive (not shown) is allowed for backward compatibility; its meaning is identical to limit transfers-in. 
The master fileconsistsof control information and a list of resource records for objects in the zone of the forms: 

$INCLUDE <f i I e n a me ><o p t _ d o mai n > 

$0RIGIN <domai n> 

domai n is . for root, @ for the current origin, or a standard domain name. If domai n isastandard domain name that does not 
end with ., the current origin is appended to the domain. Domain namesending with . are unmodified. The opt _ domai n 
field is used to define an origin for the data in an included file. It is equivalent to placing a $origin statement before the first 
lineof the included file. The field is optional. N either the opt _ domai n field nor $origin statements in the included file modify 
the current origin for this file Theopt _t 11 field is an optional integer number for the timeto-live field. It defaults to 0, 
meaning the minimum value specified in the SO A record for the zone. Theopt.ci ass field istheobjectaddresstype; 
currently only onetype issupported, 1 n, for objects connected to the D ARPA Internet. The type field contains one of the 
following tokens; the data expected in theresome. record, data field isin parentheses: 
a A host address (dotted quad). 

ns An authoritative nameserver (domain). 

mx A mail exchanger (domain), preceded by a preference value (0..32767) with lower 

numeric values representing higher logical preferences 
cname The canonical name for an alias (domain). 

soa M arks the start of a zone of authority (domain of originating host, domain address of 

maintainer, aserial number and the following paramdtersin seconds refresh, retry, 
expire, and minimum TTL (see RFC 883)). 
null A null resource record (no format or data). 

rp A responsible person for some domain name (mailbox, m-referrai). 

ptr A domain name pointer (domain). 

hinfo H ost information (cpu_type, os_type). 

Resource records usually end at the end of a line but may be continued across lines between opening and closing parentheses 
Comments are introduced by semicolons and continue to the end of the line 

Note that there are other resource record types, not shown here You should consult the Bl N D OperationsGUIDe(BOG) 
for the complete list. Some resource record types may have been standardized in newer RFC shut not yet implemented in 
this version of BIN D. 

Each master zone file should begin with an SOA record for the zone. A sample SO A record follows 



named 


0 IN SOA ucbvax.Berkeley.EDU. rwh.ucbvax.Berkeley.EDU. ( 

1989020501 ; serial 
10800 ; refresh 
3600 ; retry 
3600000 ; expire 
86400 ) ; minimum 

The SOA specifies a serial number, which should be changed each time the master file ischanged. Note that the serial 
number can be given as a dotted number, but this is a very unwise thing to do because the translation to normal integers is 
via concatenation rather than multiplication and addition. You can spell out the year, month, day of month, and 0..99 
version number and still fit inside the unsigned 32-bit size of this field. It's true that we will haveto rethink this strategy in 
the year 4294, but we're not worried about it. Secondary servers check the seri al number at intervals specified by the refresh 
time in seconds; if the serial number changes, a zonetransfer is doneto load the new data. If a master server cannot be 
contacted when a refresh isdue, the retry time specifies the interval at which refreshes should be attempted. If a master server 
cannot be contacted within the interval given by the expire time, all data from the zone is discarded by secondary servers. 
The minimum value isthetime-to-live(TTL) used by records in thefilewith no explicit time-to-live value. 


NOTES 

The boot file directives domain and suffixes have been obsoleted by a more useful resolver-based implementation of suffixing 
for partially qualified domain names. The prior mechanisms could fail under a number of situations, especially when then 
local nameserver did not have complete information. 


Thefollowing signals have the specified effect when sent to the server process using the kin(l) command: 


SIGHUP 


SIGINT 

SIGIOT 


SIGSYS 

SIGTERM 

SIGUSR1 

SIGUSR2 

SIGWINCH 


Causes server to read named.boot and reload the database. If the server is built with the 
forced reload compile-time option, then sighup also causes the server to check the serial 
number on all secondary zones U sually, theserial numbers are only checked at the 
SO A-specified intervals 

Dumps the current database and cache to /var/tmp/named_dump.db. 

Dumps statistics data into /var/tmp/named. stats if the server is compiled with -dstats. 
Statistics data is appended to the file Some systems use sigabrt rather than sigiot for 
this 

Dumps the profiling data in /var/tmp if the server is compiled with profiling (theserver 
forks, changes directories and exits). 

Dumps the primary and secondary database files. Used to save modified data on 
shutdown if theserver is compiled with dynamic updating enabled. 

T urns on debugging; each sigusri increments debug level (siGEMTon older systems 
without sigusri). 

T urns off debugging completely (sigfpe on older systems without sigusr 2) . 

Toggles logging of all incoming queries via sysiog(3) (requires server to have been built 
with the qrylog option). 


FILES 

/etc/named.boot 
/etc/named.pid 
/var/run/named.pid 
/var/tmp/named_dump.db 
/var/tmp/named.nun 
/var/tmp/named.stats 


N ameserver configuration boot file 
The process ID (on older systems) 
The process ID (on newer systems) 
D ump of the nameserver database 
D ebug output 
N ameserver statistics data 
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SEE ALSO 

kill(l), gethostbyname(3), signal(2), resolver(3), resolver(5), hostname(7), RFC 882, RFC 883, RFC 973, RFC 974, RFC 
1033, RFC 1034, RFC 1035, RFC 1123, Name Server 0 perati onsGU IDefor BIN D 

20Junel995 

named.reload 

named. reload- C ause the nameserver to synchronize its database. 

DESCRIPTION 

This command sendsasiGHUP to the running nameserver. This signal is documented in named(8). 

BUGS 

It does not check to see if the nameserver is actually running and could use a stale pid cache file, which may result in the 
death of an unrelated process 

SEE ALSO 

named(8), named.restart(8) 

26Junel993 



named.restart 

named. restart— Stop and restart the nameserver. 

DESCRIPTION 

This command sendsasiGKiu. to the running nameserver and then starts a new one. 

BUGS 

It does not check to see if the nameserver isactually running and could use a stale pid cache file, which may result in the 
death of an unrelated process 

It does not wait after killing the old server before starting a new one. Because the server could take some time to die and the 
new one experiences a fatal error if the old one isn't gone by the time it starts you can be left in a situation where you have 
no nameserver at all. 


SEE ALSO 

named(8), named.reload(8) 
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ndc 


ndc— N amedaemon control interface. 


SYNOPSIS 



netstat 


DESCRIPTION 

This command allows the nameserver administrator to send various signals to the nameserver or to restart it. Zero or more 
directives may be given from the following list: 

status D isplays the current status of named as shown by ps(l). 

dumpdb C auses named to dump its database and cacheto /var/tmp/named_dump.db (usestheiNT 

signal.) 

reload C auses named to check the serial numbers of all primary and secondary zones and to 

reload those that have changed (uses the hup signal.) 

stats C auses named to dump its statistics to /var/tmp/named. stats (usestheiOT or ABRT signal.) 

trace Causes named to increment its "tracing level" by one. Whenever the tracing level is 

nonzero, trace information is written to /var/tmp/named. run. Higher tracing levels result 
in more detailed information (uses the usri signal). 

notrace Causes named to Set its "tracing level" to zero, closing /var/tmp/named. run if it isopen 

(uses the usr 2 signal). 

query log C auses named to toggle the "query logging" feature, which results in a sysiog(3) of each 

incoming query (uses the winch signal). N otethat query logging consumes quite a lot of 
log file space Thisdirective may also be given asqryiog. 
start C auses named to be started as long as it isn't already running, 

stop C auses named to be stopped if it is running, 

restart C auses named to be killed and restarted. 

BUGS 

Arguments to named are not preserved by restart or known by start. Some mechanism for controlling the parameters and 
environment should exist. 

Implemented asa sh(l) script. 

AUTHOR 

Paul Vixie( Internet Software Consortium) 

SEE ALSO 

named(8), named.reload(8), named.restart(8) 

27 November 1994 


netstat 

netstat— D isplay active network connections 

SYNOPSIS 

netstat [[-a | [-t | -u | -w]] [-n | -o] | -x] [-c] 
netstat -r [-c] [-n] 
netstat -v 

DESCRIPTION 

netstat displays the status of network connections on either TC P, U DP, or RAW sockets to the system. By default, netstat 
only displays status on those TCP sockets that are not in the listen state (that is, connections to active processes). To obtain 
information about the kernel routing table, netstat may be invoked with the option -r. A listing of internal U N IX 
connections can beobtained by invoking ndtstat with the option -x. 
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netstat'sdisplay includesthefollowing information for each socket: 




Local Address 


Foreign Address 
(State) 


ESTABLISHED 
SYN SENT 
SYN RECV 
FIN WAIT1 
FIN WAIT2 
TIME WAIT 
CLOSED 
CLOSE WAIT 
LAST ACK 
LISTEN 
UNKNOWN 


The protocol (either TC P or U DP) used by the socket. 

The count of bytes not copied by the user program connected to this socket. 

T he count of bytes not acknowledged by the remote host. 

The local address (local hostname) and port number of the socket. Unless the-n switch 
isgiven, thesocket address is resolved to its canonical hostname and the port number is 
translated into thecorresponding service name. 

The remote address (remote hostname) and port number of thesocket. As with the local 
address: port, the -n switch turns off hostname and service name resolution. 

The state of thesocket. Because there are no states in RAW and usually no states used in 
UDP, this row may be left blank. Usually, thiscan be one of several values: 

Thesocket has an established connection. 

Thesocket isactively attempting to establish a connection. 

The connection is being initialized. 

Thesocket is closed, and the connection is shutting down. 

Connection is closed, and thesocket is waiting for a shutdown from the remote end. 
Thesocket iswaiting after close for remote shutdown re-transmission. 

The socket is not bei ng used. 

The remote end has shut down, waiti ng for the socket to close 

The remote end shut down, and the socket is closed. Waiting for acknowledgment. 

Thesocket is listening for incoming connections 

The state of the socket is unknown. 


If netstat is invoked with the option -o, additional information is displayed after the state info. This information is shown 
like this keyword (tim^backoff) and an optional asterisk. Thekeyword shows the state of the timer belonging to thesocket, 
the time displayed (in seconds) is how long it will take the timer to expire, the backoff value indicates the current retry count 
for data transmission, and the asterisk indicates that this timer is in the expiration queue. The latter might be removed in 
future but is helpful for debugging the TC P-Code for now. 


Invoked with the option -x, netstat displays a list of all active UN IX internal communication sockets 
netstat’sdisplay includes thefollowing information for each socket: 


Proto 

RefCnt 

Flags 


Type 

SOCK DGRAM 
SOCK STREAM 
SOCK RAW 
SOCK RDM 
SOCK SEQPACKET 
SOCK PACKET 


UNKNOWN 


State 

FREE 


The protocol (usually UN IX) used by the socket. 

The reference count (attached processes via thissocket). 

The only known flag to me is so accepton (displayed asAcc); otherwise, left blank, 
so accepton is used on unconnected sockets if their corresponding processes are waiting 
for a connect request. 

T here are several types of socket access: 

The socket is used in Datagram (connectionless) mode. 

This is a stream (connection) socket. 

T he socket is used as a raw socket. 

Thisoneserves reliably delivered messages. 

Thisisasequential packet socket. 

This socket type is used as a Linux-specific way to get packets at the dev (kernel) level. It 
isassumed to be used to write things such asRARP (Reverse Address Resolution 
Protocol) and similar thingson the user level. 

Who ever knows, what future will bring; just fill in here :-) 

Thisfield will contain one of thefollowing keywords 
T he socket is not allocated. 
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LISTENING 

UNCONNECTED 

CONNECTING 

CONNECTED 

DISCONNECTING 

UNKNOWN 

Path 


The socket is listening for a connection request. 

The socket is not connected to another one 
The socket is about to establish a connection. 

The socket is connected. 

T he socket is disconnecting. 

This state should never happen. 

This displays the pathname that the corresponding processes attached to the socket. 


The network routing table (invoked with netstat -r) shows up the following information: 

Destination net/address The destination address of a resolved host or hand-entered network is displayed. Unless 

the option -n is given, the hosts or nets are resolved. An entry named default shows up 
the default route for the kernel. 

G ateway address If there is no asterisk (*) displayed, any data is routed to thededicated gateway. 

Flags Possible routing flags are 

u This route is usable. 

g D estination is a gateway. 

h Destination is a host entry. 

n Destination is a Net entry. 

r Route will be reinstated after timeout. 

d This one is created dynamically (by redirection). 

m This one is modified dynamically (by redirection). 


RefCnt 
Use 
I face 

OPTIONS 


Reference count for this route. 

How many times this route was used yet. 

T his is the name of the interface where this route belongs 


D isplay information about all Internet sockets, such asTC P, U D P, and RAW, 
including those sockets that are listening only. 

G enerate a continuous listing of network status network status is displayed every second 
until the program isinterrupted. 

C auses netstat not to resolve hostnames and service names when displaying remote and 
local address and port information. 

D isplay timer states expiration times, and backoff state. 

D isplay kernel routing table. 

Display information about TCP sockets only, including those that are listening. 

D isplay information about U D P sockets only. 

Print version information. 

D isplay information about raw sockets. 

D isplay information about UNIX domain sockets. 


FILES 

/proc/net/tcp 

/proc/net/udp 

/proc/net/raw 

/proc/net/unix 


TCP socket information 
U D P socket information 
RAW socket information 
UNIX domain socket information 
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/proc/net/route Kernel routing information 

/etc/services T he services translation 

BUGS 

N one reported yet (5/20/93). 

AUTHORS 

Thenetstat user interface was written by Fred Baumgarten (dc6iq@insui.etec.uni-karisruhe.de). The man page is basically 
by Matt Welsh (mdw@tc.cornell.edu). 

Cohesve Systems 20 M ay 1993 


makeactive,makehistory,newsrequeue 

makeactive, makehistory, newsrequeue— Tools to recover Usenet databases 

SYNOPSIS 

makeactive [ -m ][-o ] 

makehistory [ -b ][ -f filename ][-i ][-n ][-o ][-r ][-s size ] 

[-T t mpdi r ][-u [ -v] ] 

newsrequeue! -a active ] [ -h history ] [-d days ] [-1 ][-n news f eeds ] [i nput ] 

DESCRIPTION 

makeactive invokes f ind(l) to get a list of all directories in the news spool tree, / news/spooi. It discards directories named 
iost+found as well as those that have a period in them. It scans all other directories for all-numeric filenames and determines 
the highest and lowest number. T he program's output is a set of active(5) file lines. Because there is no way to know if a 
group is moderated or disabled, the fourth field of all entries isy. Also, mid-level directories that aren't newsgroups are also 
created as newsgroups with no entries. (For example, there is a comp, sources, unix group, but no comp, sources.) 

If the -o flag is used, makeactive reads an existing active filefor the list of group names and just renumber all groups. It 
preserves the fourth field of theactive file if one is present. Thisisanalogousto thectiinnd(8) renumber command, except 
that innd(8) should be throttled or not running. Do not usethisflag with output redirected to the standard active file! 

If the -m flag isgiven, then makeactive attempts to adjust the highest and lowest article numbers wherever possible. If articles 
are found in a newsgroup, the numbers reflect what wasfound. If no articles are found in a newsgroup, the high number 
from theold file is kept, and the low number isset to one more than the high number. Thisflag may only be used if the -o 
flagisused. 

makeactive exits with nonzero status if any problems occur. A typical way to use the program is with thefollowing /bin/sh 
commands 

ctlinnd throttle "Rebuilding active file" 

TEMP=${TMPDIR - / tmp} / act$$ 
if [ -f /var/lib/news/active ] ; then 
if makeactive -o >${TEMP} ; then 
mv ${TEMP} /var/lib/news/active 


if makeactive >${TEMP} ; then 

# Edit to restore moderated 

# and aliased groups. 

mv ${TEMP} /var/lib/news/active 


ctlinnd reload 


file" 



makeactive, makehiiory, newsrequeue 


makehistory rebuilds the history(5) text file and the associated dbz(3) database. The default name of the text file is 
/news/iib/history; to specify a different name use the -f flag, makehistory scans the active(5) file to determine which 
newsgroup directories within the spool directory, /news/spooi, should be scanned. (If a group is removed, but its spool 
directory still exists, makehistory ignores it.) The program reads each file found and writes a history linefor it. If the -b flag 
is used, then makehistory removes any articles that do not have valid M essage-ID headers in them. 

After the text file is written, makehistory builds the dbz database. If the -f flag is used, then the database files are named 
file.dir and fiie.pag. If the -f flag is not used, then a temporary link to the name history, n is made and thedatabasefiles 
are written as history, n.pag and history, n. dir. If the -o flag is used, then the link is not made and any existing history files 
are overwritten. If theold database exists, makehistory usesitto determine the sizeof the nav database T o ignore theold 
database, use the -i flag. U sing the -o flag implies the-i flag. Theprogram also ignores any old database if the -s flag is used 
to specify the approximate number of entries in the nav database Accurately specifying the size is an optimization that 
creates a more efficient database. (The size should be the estimated eventual size of the file typically the size of theold file.) 
For more information, see the discussion of dbzfresh and dbzsize in dbz(3). 

If the -u flag isgiven, then makehistory assumes that innd is running. It pauses the server while scanning and then sends 
addhist commands (see ctiinnd(8)) to the server for any article that is not found in the dbz database The command 
makehistory -bu is useful after a system crash to delete any mangled articles and bring the article database back into a more 
consistent state. If the -v flag is used with the-u flag, then makehistory puts a copy of all added lines on its standard output. 
To scan the spool directory without rebuilding the dbz files, use the -n flag. If used with -u, the server is not paused while 
scanning. To just build the dbz files from an existing text file use the -r flag. The -i or -s flags can be useful if there are no 
valid dbz files to use. A typical way to use this program is with the following /bin/sh commands 

ctlinnd throttle "Rebuilding history file" 
cd /news/lib 

if makehistory -n -f history.n ; then 

echo Error creating history file! 
fi 

# The following line can be used to retain expired history. 

# It is not necessary for the history file to be sorted. 

# awk 1 NF==2 { print; }' chistory »history.n 

# View history file for mistakes. 

if makehistory -r -s 'wc -1 <history' -f history.n; then 

mv history.n history 

mv history.n.dir history.dir 

mv history.n.pag history.pag 

fi 

ctlinnd go " 

makehistory needs to create a temporary file that contains one linefor each article it finds, which can become very large. This 
file is created in the /tmp directory. T he tmpdir environment variable may be used to specify a different directory. Alterna¬ 
tively, the -t flag may be used to specify a temporary directory. I n addition, the sort(l) that is invoked during the build 
writes large temporary files (often to /var/tmp, but see your system man pages). If the -t flag is used, then the flag and its 
value are passed to sort. 0 n most systems this changes thetemporary directory that sort uses If used, thisflagand its value 
are passed on to the sort(l) command that is invoked during the build. 

makehistory doesnot handle symbolic links If the news spool area is split across multi pie partitions the following commands 
should probably be run before the database is regenerated: 

cd /news/spool 

find . -type 1 -name '[1-9]*' -print | xargs -t rm 

M ake sure to run the command on all the appropriate partitions! 
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newsrequeue can beused to rewrite batchfiles after a system crash. It operates in two modes In thefirst mode it first reads 
the a c t i ve and ne»sf eeds (5) files to determine where the different newsgroups are to be distributed. To specify alternate 
locationsfor these files, use the-a or-n flags It then opens the hi story database. To specify a different file usethe-hflag. 
Once the files are opened, newsrequeue reads from the specified input file or standard input if no file is specified. Each line 
should have a single M essage-ID, surrounded in angle brackets; any other text on the line is ignored. For example the 
history file (or a trailing subset of it) is acceptable input to the program operating in this mode. If the -d flag is used, then 
only articles that were received within thespecified number of days are processed. 

newsrequeue uses the first two fields of the newsfeed entry— the sitename and the excludes field and the patterns and 
distribs field. It ignores all flags in the third field except for the n field and also ignores thefourth field altogether. 

The second mode is used if the -1 flag is used. In this mode, it reads from thespecified input file or standard input if no file 
isspecified. Each line should look like an innd log entry. It parses entries for accepted articles looks up the M essage-ID in 
the history database to get thefilename, and then scans the list of sites. 

In either mode the output of newsrequeue consists of one line for each article that should be forwarded. Each such line 
contains the M essage-ID, thefilename and the list of sites that should receive the article. Theoutput is suitable for piping 
into filechan(8). 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

active(5), ctlinnd(8), dbz{3), filechan(8), history(5), innd(8), newsfeeds(5) 

news.daily 

news.daily— Do regular Usend: system administration 

SYNOPSIS 

news.daily [ keyword... ] 

innwatch [ -t si eept i me ][-f controlfile ] [ -1 IogfiIe ] 
expire™ file 

inncheck [ -v ] [ -pedant i c ] [ -p e r ms [ -fin ] ] [ - n o p e r ms ] [f i I e... ] 

DESCRIPTION 

news, daily performs a number of important Usendt administrative functions. This includes producing a status report, 
removing old news articles, processing log files, rotating the archived log files, renumbering the active file, removing any old 
socket filesfound in thefirewall directory, and collecting the output. This program should be run under the news 
admi nistrator's ID, not as root. 

Bydefault, news.daily performs all its functions and mailsthe output to the newsadministrator, Usenet. By specifying 
keywords on thecommand line, it is possibleto modify the functions performed, aswdl as change the arguments given to 
expire(8) and expireover(8). 

news.daily should be run onceaday, typically out of cron(8). It may be run more often, but such invocations should at least 
use the norotate keyword to prevent the log files from being processed and rotated too fast. 

Theshiock(l) program isused to prevent simultaneous executions. 

The following keywords may beused: 

delay™ This usesthe -z flag when invoking expire and expireover. T he names of articles to be 

removed are written to a temporary file and then removed after expiration by calling 
expirerm. 
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nostat 

noexpire 

noexplog 

flags='expire\args' 

nologs 

norotate 


norenumber 


nomail 


expireover 

expireoverflags= 1 explreovernargs 1 

/full/path 


This keyword disables the status report generated by innstat (see newsiog(8)). W ithout 
this keyword, the status report isthe first function performed, just prior to obtaining the 
news.daily lock. 

By default, expire isinvoked to remove old news articles Using this keyword disables 
thisfunction. 

expire usually appends information to /var/log/news/expire.log (see newsiog(5)). Using 
thiskeyword causes the expire output to be handled as part of news, daily's output. It 
has no effect if the noexpire keyword is used. 

By default, expire isinvoked with the an argument of -vi. Using this keyword changes 
the arguments to those specified. Be careful to use quotes if multiple arguments are 
needed. Thiskeyword has no effect if the noexpire keyword is used. 

After expiration, scaniogs(8) isinvoked to process the log files Using this keyword 
disables all log processing functions. 

By default, log processing includes rotating and cleaning out log files U sing this 
keyword disables the rotating and cleaning aspect of the log processing. The log files are 
only scanned for information and no contents are altered. Thiskeyword has no effect if 
the noiogs keyword is used. 

This keyword disables the ctnnnd(8) renumber operation. U sually, the low watermark 
for all newsgroups (see active(5)) is reset. 

By default, any socket ctunnd socket that has not been modified for two days is 
removed. Using this keyword disables thisfunction. 

news.daily usually sends a mail message containing the results to the administrator. 
Using this keyword causes this message to be sent to stdout and stderr instead. Usually, 
all utilities invoked by thescript have their stdout and stderr redirected into afile. If the 
file is empty, no message is sent. 

T he expireover program is called after expiration to purge the overview databases 
If the expireover keyword isused, thiskeyword may be used to specify the flags to be 
passed to expireover. If the delay™ keyword isused, then the default value is -z and the 
list of deleted files; otherwise, the default value is-s. 

The program specified by the given path isexecuted just before any expiration is done. 

A typical use isto specify an alternate expiration program and use the noexpire keyword. 
M ultiple programs may be specified; they are invoked in order. 


The norotate keyword is passed on to scaniogs if it isinvoked. expire™ is a script that removes a list of files The specified 
file lists thefiles. It is sorted and then fed into a pipeline responsible for doing the removal, usually fastrm(8). If there seemed 
to be a problem removing thefiles then mail is sent to the news administrator. If there were no problems, then file is 
renamed to /var/iog/news/expire.nst where it is kept (for safety) until the next day’s expiration, 
innwatch is a script that can be started at news boot time. It periodically—every si eepti me seconds— examines the load 
average and the number of freeblocksand inodes on the spool partition, as described by its control file, innwatch. cti(5). If 
the load gdtstoo high or the disk gets too full, it throttles the server. When the condition restores it unblocks the server. In 
addition, on each passthrough the loop, it checks the specified log file to see if it has been modified and sends mail to the 
news administrator if so. It isusually a good idea to set thisto the sysiog(3) file that receives critical news messages U pon 
receipt of an interrupt signal, innwatch reports its status in the file /news/iib/innwatch. status, 
inncheck isa peri(l) script that verifies the syntax and permissions of all I nterNetNews configuration files. If no files are 
specified, it checks all files. A filename may be followed by an equal sign and a path to indicate the pathname to useforthe 
file. For example newsfeeds=/tmp/nf checks the syntax of anew newsfeeds(5) without requiring it to be installed. Ifthe-v 
flag isused, it prints status information as it checks each file If the -pedantic flag isused, it checks the files for omissionsthat 
are not strictly errors but might indicate a configuration error. 

If any file isspecified, only the permissionson thosefilesare checked. The -noperas flag suppressesthischeck. If the -perms 
flag isused, thescript verifies the ownership and permissions of all files The-fix flag can also be used so that the output can 
be executed as a shell script. 
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HISTORY 

news.daily and this manual page were written by Landon Curt Noll (chongo@toad.com) and Rich $alz (rsaiz@uunet.uu.net). 
inncheck was written by Brendan Kehoe(brendan@cs.widener.edu) and Rich, 
innwatch Was Written byM ike Cooper (mcooper@usc.edu) and (kre@munnari.oz.au). 

SEE ALSO 

active(5), ctlinnd(8), expire(8), fastrm(8), newslog(5), newslog(8), innwatch.ctl(5), shlock(l) 

newslog 

newsiog— M aintenanceof Usenet log files 

SYNOPSIS 

scanlogs [ norotate ][nonn ] 
innstat 

tally.unwanted 
tally.control 

DESCRIPTION 

scanlogs summarizes the information recorded in theiNN log files (see newsiog(5)). Bydefault, it also rotates and cleans out 
the logs It is usually invoked by the news. daiiy(8) script. 

Thefollowing keywords are accepted: 

norotate U sing this keyword disables the rotating and cleaning aspect of the log processing: 

The logs files are only scanned for information and no contents are altered, 
nonn Usually, thenn log file is scanned and rotated. Using this keyword disablesthis 

function. 

If scanlogs is invoked more than once a day, the norotate keyword should be used to prevent premature log cleaning. 

The writeiog scri pt is used to write a log entry or send it as mail. T he name parameter specifies the name of the log file where 
the entry should be written. If it istheword man, then theentry is mailed to the news administrator, Usenet. The data that 
is written or sent consists of the text given on thecommand line, followed by standard input indented by four spaces. 
shiock(l) is used to avoid simultaneous updates to a single log file 

The innstat script prints a snapshot of theiNN system. It displays the operating mode of the server, as well as disk usage and 
the status of all log and lock files 

The rest of the scripts described here are usually invoked by scanlogs. They parse log files that are described in newsiog(5) 
and the server's article log file described in innd(8). 

tally, unwanted script parses the article log file to update the cumulative list of articles posted to unwanted newsgroups, 
unwanted.log. 

tally.control reads its standard input, which should bethenewgroup.log and rmgroup.log log files. It updatesthecumulative 
list of newsgroup creations and deletions, control, log. 

inniog.awk isan awk(l) script that summarizes the activity thatinnd and nnrpd(8) report to sysiog. 

HISTORY 

Written by Landon Curt Noll (chongo@toad.com) and Rich $alz(rsaiz@uunet.uu.net) for InterNetN ews. 
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SEE ALSO 

innd(8) newslog(5), news.daily(8), nnrpd(8) 

nfsd 

nfsd— N FS service daemon. 

SYNOPSIS 

/usr/etc/rpc.nfsd [\-f\exponts-file\][\-dhnprv\] 
[\--debug\][\--exports-file=f i I e \] [\--help\] 

[\--allow-non-root\][\--re-export\][\--version\] 


DESCRIPTION 

The nfsd program isan N FS service daemon that handles client filesystem requests. Unlike nfsd on some other systems, nfsd 
operates asa normal user-level process The server also differs from other N FS server implementations in that it mounts an 
entire file hierarchy not limited by the boundaries of physical filesystems The implementation allows the clients read-only or 
read-write access to the file hierarchy of the server machine. 

Themountd program starts an ancillary user-level mount daemon. 

OPTIONS 

-f or --exports-file 

-d Or - -debug 
-hor - -help 
-n Or - -allow-non-root 

-p Or - -promiscuous 
-r Or --re-export 


-vor - -version 

SEE ALSO 

exports(5), mountd(8), ugidd(8C) 

AUTHORS 

M ark Shand wrote the original unfsd. Don Becker extended unfsd to support authentication and allow read-write access and 
called it hnfs. Rick Sladkey added host matching, showmount -e support, mountd authentication, inetd support, and all the 
portability and configuration code 

13 October 1993 


This option specifies the exports file, listing thedients that this server is prepared to 
serve and parameters to apply to each such mount (seeexports(5)). By default, exports 
are read from /etc/exports. 

Log each transaction verbosely to the sysiog. 

Provide a short help summary. 

Allow incoming N FS requests to be honored even if they do not originate from reserved 
IP ports Some older N FS client implementations require this Some newer N FS client 
implementations don't believe in reserved port checking. 

Put theserver into promiscuous mode where it serves any host on the network. 

Allow imported N FS filesystems to be exported. This can be used to turn a machine 
into an N FS multiplier. Caution should be used when re-exporting loopback N FS 
mounts because re-entering the mount point results in deadlock between the N FS client 
and the N FS server. 

Report the current version number of the program. 


nnrpd 

nnrpd- N N T P server for on-campus hosts. 
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SYNOPSIS 

nnrpd [ -r reason ][-s title padding ][-S host ][-t ] 

DESCRIPTION 

nnrpd isan N NTP server for newsreaders. It accepts commands on its standard input and respondson its standard output. 

It isusually invoked by innd(8) with those descriptors attached to a remote client connection. 

If the-r flag is used, then nnrpd rqects the incoming connection giving reason as the text. Thisflag is used byinnd when it is 
paused or throttled. 

Unlike innd, nnrpd supports all N NTP commands for user-oriented reading and posting. 

nnrpd uses the nnrp.access(5) fileto control who is authorized to access the Usenet database. It also rqects connections if the 
load average is greater than 16. 

Aseach command is received, nnrpd tries to change its argv array so that ps(l) prints the command being executed. To get a 
full display, the -s flag may be used with a long string as its argument, which is overwritten when the program changes its 
title 

On exit, nnrpd reports usage statistics through sysiog(3). 

If the-t flag is used, all client commands and initial responses are traced by reporting them in sysiog. Thisflag is set by innd 
under the control of thectiinnd(8) trace command and is toggled upon receipt of asiGHUP; seesignai(2). 

If the-s flag is used, all postings are forwarded to the specified host, which should bethe master N NTP server. Thisflag is 
set by innd if it is started with the -s flag. 

nnrpd can accept multimedia postings that follow the M IM E standard as long as such postings are also acceptable as SM T P 
messages See the discussion oftheM IM E headersin inn.cont(5). 

PROTOCOL DIFFERENCES 

nnrpd implements the N N T P commands defined in RFC 977 with the following differences 

■ Theihave command is not implemented. Users should be using the post command to post articles. 

■ The slave command is not implemented. This command has never been fully defined. 

■ The list command may be followed by the optional word active, times, distributions, distrib.pats, newsgroups, or 
overview.fmt to get a list of when newsgroups where created, a list of valid distributions a file specifying default 
distribution patterns, a one-per-line description of the current si of newsgroups or a listing of the overview. fmt(5) file 
The command list active is equivalent to theiist command. Thisisacommon extension. 

■ Thexhdr, authinto user, and authinto pass commandsare implemented. These are based on the reference U NIX 
implementation; no other documentation isavailable 

■ A new command, xpat header range ]MessageiD pat [morepat...], is provided. Thefirst argument is the case-insensitive 
name of the header to be searched. T he second argument is either an article range or a single M essage-ID as specified in 
RFC 977.The third argument is a wiidmat(3)-style pattern; if there are additional arguments, they are joined together 
separated by a single space to form thecomplete pattern. This command issimilarto thexhdr command. It returnsa 221 
response code followed by thetext response of all article numbers that match the pattern. 

■ The ustgroup group command isprovided. This isa comment extension. It is equivalent to thegroup command, except 
that the reply is a multi-line response containing the list of all article numbers in the group. 

■ The xgtitie [group] command isprovided. This extension is used by AN U-News It returns a 282 reply code followed 
by a one-line description of all newsgroups that match the pattern. The default is the current group. 

■ Thexover [range] command isprovided. It returns a 224 reply code, followed by the overview data for the specified 
range; the default is to return the data for the current article. 

■ Thexpath Messaged command isprovided; see innd(8). 

■ The date command isprovided; this is based on the draft N NTP protocol revision. It returns a one-line response code 
of 111 followed by theGMT date and time on the server in theform YYYYMMDDhh mms s. 



nntpsnd 


1349 


HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for I nterN dtN ews. 0 verview support added by Rob Robertston 
(rob@vioiet.berkeiey.edu) and Rich in January 1993. 

SEE ALSO 

ctlinnd(8), innd(8), inn.conf(5), nnrp.access(5), signal(2), wildmat(3) 

nntpsend 

nntpsend-Send Usenet articles to remote site. 

SYNOPSIS 

nntpsend [ -d ] [-p ][-r ] [-S ] [-s size ] [-t timeout ] 

[ - T t i me I i mi t ][sitename fqdn ] ... 

DESCRIPTION 

nntpsend is a front end that invokes innxmit(l) to send Usenet articles to a remote N NTP site 

The sites to be fed may be specified by givingsi tename fqdn pairs on the command line If no such pairs are given, nntpsend 
defaults to the information given in the nntpsend. cti(5) configfile 

T he s i t e n a me should be the name of the site as specified i n the newsf eeds(5) file T he f q d n should be the hostname 
or IP address of the remote site. An innxmit is launched for sites with queued news All innxmit processes are 
spawned in the background and the script waits for them all to finish before returning. 0 utput issentto the file 
/var/iog/news/nntpsend. log. To avoid overwhelming the local system, nntpsend waits five seconds before spawning 
each child. Theflag -a isalwaysgiven asaflagto innxmit. 

nntpsend expects that the batchfilefor a site is named /news/spooi/out .going/si t ename . T o prevent batchfile corruption, 
shiock(l) is used to "lock" these files 

The-p, -r, -s, -t, and -t flags are passed on to the child innxmit program. N otethat if the -p flag is used then no connection 
is made and no articles are fed to the remote site. It is useful to havecron(8) invoke nntpsend with this flag in case a site 
cannot be reached for an extended period of time 

If the-s flag is used, then shrinkfiie(l) is invoked to perform a tail truncation on the batchfile and theflag is passed to it. 
When si tename fqdn pairs are given on the command line, any flags given on the command completely describe how innxmit 
and shrinkfiie operate. When no such pairs are given on thecommand line then the information found in nntpsend.cti 
becomes the default flags for that site. Any flags given on the command line override the default flags for the site. 

For example, with thefollowing control file 

nsavax:erehwon.nsavax.gov::-S -t60 

group70:group70.org:: 

walldrug:walldrug.com:1m:-T1800 -t300 

Thecommand 

nntpsend 

will result in thefollowing: 

Sitename Truncation Innxmit flags 

nsavax (none) -a -S -t60 

group70 (none) -a -tl80 

walldrug 1m -a -T1800 -t300 
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The command 

nntpsend -d -T1200 

will result in thefollowing: 

Sitename Truncation Innxmit flags 

nsavax (none) -a -d -S -T1200 -t60 

group70 (none) -a -d -T1200 -t180 

walldrug Ira -a -d -T1200 -t300 

The command 

nntpsend -s 5m -T1200 nsavax erehwon.nsavax.gov group70 group70.org 

will result in thefollowing: 

Sitename Truncation Innxmit flags 

nsavax 5m -a -T1200 -tl80 

group70 5m -a -T1200 -tl80 

Remember that -a is always given, and -t defaults to 180. 

HISTORY 

Written by Landon Curt Noll (chongo@toad.com) and Rich $alz (rsaiz@uunet.uu.net) for I nterN etN ews. 

SEE ALSO 

innxmit(l), newsfeeds(5), nntpsend.ctl(5), shrinkfile(l) 

nslookup 

nsiookup— Q uery I nterndt nameservers interactively. 

SYNOPSIS 

nslookup [ -option ... ] [ host-1 o-find | -[server ]] 

DESCRIPTION 

nslookup isa program to query I nternet domain nameservers. nslookup has two modes: interactive and non-interactive. 
Interactive mode allows the user to query nameserversfor information about various hosts and domainsor to print a list of 
hosts in adomain. Non-interactive mode is used to print just the name and requested information for a host or domain. 

ARGUMENTS 

Interactive mode is entered in thefollowing cases: 

■ W hen no arguments are given (the default nameserver is used) 

■ When thefirst argument is a hyphen (-) and the second argument is the hostname or Internet address of a nameserver 
Non-interactive mode is used when the name or I nternet address of the host to be looked up is given as the first argument. 
The optional second argument specifies the host name or address of a nameserver. 

The options listed under the set command can be specified in the .nsiookuprc file in the user's home directory if they are 
listed one per line. Options can also be specified on the command line if they precede the arguments and are prefixed with a 
hyphen. For example, to change the default query type to host information, and the initial timeout to 10 seconds, type: 
nslookup -query=hinfo -timeout=10 



nslookup 


INTERACTIVE COMMANDS 


Commands may be interrupted at any time by typing Ctrl+C. T o exit, type Ctrl 40 (EO F) or type exit. The command-line 
length must be less than 256 characters. To treat a built-in command as a hostname, precede it with an escape character (n). 
Note that an unrecognized command is interpreted asahostname. 








finger [name][> f 
finger [ n a me][» 


Is [opt 
Is [opt 


I] domain [> filename], 
i ] domai n [» filename] 


Look up information for host using the current default server or using server if 
specified. If host isan Internet address and the query type isA or ptr, the name of the 
host is returned. If host isa name and does not have a trailing period, the default 
domai n name is appended to the name. (This behavior depends on the state of the 
set options domain, srchlist, defname, and search). T0 look Up a host not in the Current 
domain, append a period to the name. 

Change the default server to domai n. lserver uses the initial server to look up informa¬ 
tion about domai n, whereas server uses the current default server. If an authoritative 
answer can't be found, the names of servers that might have the answer are returned. 

C hanges the default server to the server for the root of the domain name space. 

C urrently, the host ns. internic. net is used. (This command is a synonym for lserver 
ns.internic.net.) The name of the root server can be changed with the set root 
command. 

Connects with the finger server on the current host. The current host is defined when 
a previous lookup for a host was successful and returned address information (seethe 
set query-type= a command), name is optional. > and » can be used to redirect output 
in the usual manner. 

List the information available for domain, optionally creating or appending to 
fi i ename. The default output contains hostnames and their Internet addresses, option 
can be one of the following: 

-t quer yt ype Lists all records of the specified type (see 

querytype). 

-a Lists aliases of hosts in the domain. Synonym for 

-t CNAME. 

-d Lists all recordsfor the domain. Synonym for 


-h 




help, ? 


set keyword[=*alue] 


ListsC PU and operating system information for 
the domain. Synonym for -t hinfo. 

Lists well-known services of hosts in the domain. 
Synonym for -t wks. When output is directed to a 
fi le, hash marks are pri nted for every 50 records 
received from the server. 

Sorts and lists the output of previous is commands 
with mone(l). 

Prints a brief summary of commands. 

Exits the program. 

This command is used to change state information 
that affects the lookups. Valid keywords are 


an Pri nts the current values of the frequentl y used 

optionsto set. Information about the current 
default server and host is also printed. 

Change the query class to oneofthefollowing: 
in The Internet class. 


CHAOS 


The Chaos class 
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[nojdebug 
[no]d2 
domain=name 


[no]defname 

[no]search 


querytype=r/a! ue, type=* a I ue 


[nojrecurse 

retry=numbe 


hesiod TheM IT Athena H esiod class. 

any W i Idcard (any of the above). 

The class specifiesthe protocol group of the information. (Default = in, abbreviation = 
cl.) 

Turn debugging modeon. A lot more information is printed about the packet sent to 
theserver and the resulting answer. (Default = nodebug, abbreviation = [no] deb.) 

T urn exhaustive debugging modeon. Essentially, all fields of every packet are printed. 
(Default =nod2.) 

Change thedefault domain name to name. The default domain name is appended to a 
lookup request depending on the state of the def name and search options. The domain 
search list contains the parents of the default domain if it has at least two components in 
its name. For example if the default domain iscc.Berkeiey.EDu, the search list is 
cc. Berkeley. edu and Berkeley. edu. U se the set srchiist command to specify a different 
list. Use the set all command to display the list. (Default = value from hostname 
/etc/resoiv.cont, or localdo-main, abbreviation =do.) 

Change the default domain name to n a me 1 and the domain search list to n a me 1, name 2, 
and so on. A maximum of six names separated by slashes (/) can be specified. For 
example, set srchiist=ics.Mu.EDu/ai.MiT.EDu/MiT.EDusetsthedomain to ics.mit.edu 
and the search list to the three names. This command overrides the default domain 
name and search list of the set domain command. Use the set an command to display 
the list. (Default = value based on hostname /etc/resoiv.cont, or local-domain, 
abbreviation =srchi.) 

If set, append thedefault domain name to a singlecomponent lookup request (that is, 
one that does not contain a period). (Default = def name, abbreviation = [nojdef.) 

If the lookup request contains at least one period but doesn't end with a trailing period, 
append the domain names in the domain search list to the request until an answer is 
received. (Default = search,abbreviation =[no]sea.) 

C hange the default TCP/UD P nameserver port to vai ue. (Default =53, abbreviation = 
po.) 

Change thetype of information query to one of thefollowing: 

a The host's I nterndt address 

cname The canonical name for an alias. 

hinfo ThehostCPU and operating system type. 

minfo Themailboxormail list information. 

mx The mail exchanger. 

ns The nameserver for the named zone 

ptr The host name if the query isan Internet address otherwise the pointer 

to other information. 

soa The domain's" start- of - auth 0 r i ty" information. 

txt Thetext information. 

uinfo Theuser information. 

wks The supported well-known services. 

Other types (any, axfr, mb, md, mf, null) are described in the RFC-1035 document. 
(Default = a, abbreviations=q, ty.) 

Tell the nameserver to query other servers if it does not have the information. (D efault = 
recurse, abbreviation = [no]rec.) 

Set the number of retries to number . When a reply to a request is not recdved within a 
certain amount of time (changed with set timeout), thetimeout period isdoubled and 
the request is resent. T he retry value controls how many times a request is resent before 
giving up. (Default =4, abbreviation =ret.) 




overchan 


timeout=n umber 

[nojignoretc 


Changethenameof the root server to host . This affects the root command. (Default = 
ns.internic.net, abbreviation = ro.) 

Change the initial timeout interval for waiting for a reply to number seconds Each retry 
doubles the timeout period. (Default =5 seconds, abbreviation =ti.) 

Always use a virtual circuit when sending requests to the server. (Default =novc, 
abbreviation =[no]v.) 

Ignore packet truncation errors (Default =noignoretc, abbre/iation = {no]tg.) 


DIAGNOSTICS 


If the lookup request was not successful, an error message is printed. Possible errors are 


No response from server 
No records 


Connection 
Network is 


Server failure 


Refused 


The server did not respond to a request after a certain amount of time (changed with 
set timeout=«ai ue) and acertain number of retries (changed with set retry=«ai ue). 
No nameserver is running on the server machine 

The server does not have resource records of the current query type for the host, 
although the hostname is valid. The query type is specified with the set querytype 
command. 

T he host or domain name does not exist. 

The connection to the name or finger server could not be made at the current time. 
This error commonly occurs with is and finger requests. 

The nameserver found an internal inconsistency in its database and could not return a 
valid answer. 

The nameserver refused to service the request. 

The nameserver found that the request packet was not in the proper format. It may 
indicate an error in nsiookup. 


FILES 

/Etc/Resolv.Conf 
$H0ME/.nslookuprc 
/usr/share/misc/nsiookup.help 


Initial domain name and nameserver addresses 
User's initial options. 

Summary of commands 


ENVIRONMENT 

hostaliases Filecontaining host aliases 

localdomain 0 verrides default domain. 


SEE ALSO 

resoiver(3), resoiver(5), named(8), RFC 1034 "Domain Names- Concepts and Facilities," RFC 1035 "Domain Names- 
Implementation and Specification" 

AUTHOR 

Andrew Cheren son 

24Junel990 


overchan 

overchan— U pdate the news overview database. 
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SYNOPSIS 

overchan [ -D di r ] [-c ] [f i I e ... ] 

DESCRIPTION 

overchan reads article data from files or standard input if none are specified. (A single dash in thefile list means to read 
standard input.) It uses this information to update the news overview database overchan isdesigned to be used by 
I nterN dtN ews or the C N ews mkov packages to update the database as the arti des come i n. T he database for each newsgroup 
is stored in a file named .overview in a newsgroup directory within the overview database tree. 

overchan locks the database file (by locking an auxiliary file) before appending the new data. To purge data after articles have 
been expired, see expireover(8). 

Bydefault, overchan processes its in put as an inn overview stream written asawoentryinthenewsfeeds(5)file: 

overview:*:Tc,WO:/news/bin/overchan 

This data consists of a line of text separated into two parts by a tab. T he first part is a list of all relative pathnames where the 
article has been written with a single space between entries. The second part is the data to be written into the overview file, 
except that the initial article number is omitted. 

To processtheoutput of the mkov(8) program, use the-c flag. Thisformat isdescribed in thenov distribution. 

T he -d flag can be used to specify where the databases are stored. T he default directory is / news/ spool. 

HISTORY 

Written by Rob Robertson (rob@vioiet.berkeiey.edu) and Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

newsfeeds(5), newsoverview(5), newsoverview (8) 

pac 

pac— Printer/plotter accounting information. 

SYNOPSIS 

pac [-P printer] [-c] [ -m] [-p price] [ -s] [ -r] [name ...] 

DESCRIPTION 

pac reads the printer/plotter accounting files, accumulating the number of pages (the usual case) or feet (for raster devices) of 
paper consumed by each user and printing how much each user consumed in pages or feet and dollars. 

Options and operands available: 

-p printer Accounting is done for the named printer. Usually, accounting is done for the default 

printer (site dependent), or the value of the environment variable printer is used. 

-c Flag causes the output to be sorted by cost; usually, the output is sorted alphabetically 

by name. 

-m Flagcausesthehostnameto beignored in the accounting file. Thisallowsfor a user on 

multiple machines to have all hisprinting charges grouped together. 

-p price T he value price is used for the cost in dollars instead of the default value of 0.02 or the 

price specified in /etc/printcap. 

-r Reverse the sorting order. 

-s Accounting information is summarized on the summary accounting file; this summari¬ 

zation is necessary because on a busy system, the accounting file can grow by several 
lines per day. 



Statistics are only printed for users named; usually, statistics are printed for every user 
who has used any paper. 


FILES 

/var/account/?acct Raw accounting files 

/var/account/?_sum Summary accounting files 

/etc/printcap Printer capability database 

SEE ALSO 

printcap(5) 

BUGS 

The relationship between thecomputed price and reality isasyet unknown. 

HISTORY 

Thepac command appeared in BSD 4.0. 

BSD 4.2,16 M arch 1991 


pcnfsd 

pcnfsd— (PC )N FS authentication and print request server 

SYNOPSIS 

/usr/etc/rpc.pcnfsd 

AVAILABILITY 

This program isfreely redistributable. 

DESCRIPTION 

pcnfsd isanRPC server that supportsONC clients on PC (DOS, OS/2, M acintosh, and other) systems This page describes 
version 2 of the pcnfsd server. 

rpc. pcnfsd may be started from /etc/rc.local or by the inetd(8) superdaemon. It reads the configuration file 
/etc/pcnfsd.conf if present and then services RPC requests directed to program number 150001. This release of the pcnfsd 
daemon supports both version 1 and version 2 of the pcnfsd protocol. Consult the rpcgen source file pcnfsd. x for details of 
the protocols 

The requests serviced by pcnfsd fall into three categories: authentication, printing, and other. Only the authentication and 
pri nti n g servi ces h ave ad m i n i strati vesignificance 

AUTHENTICATION 

When pcnfsd receives a pcnfsd auth or pcnfsd 2 auth request, it "logs in" the user by validating the username and password 
and returning the corresponding U ID, G IDs home directory, and umask. If pcnfsd was built with thewTMP compile-time 
option, it also appends a record to thewtmp(5) database. If you do not want to record PC logins in this way, you should add a 
line of the form 
wtmp off 

to the/etc/pcnfsd.conf file. 

Bydefault, pcnfsd only allows authentication or print requests for users with U IDs in the range 101 to 60002. (This 
corresponds in svr4 to the range for non-system accounts.) To override this, you may add a line of the form 
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uidrange r ange[ ,r ange ]... 

to the /etc/pcnfsd.conf file. H ere, each range isof theform ui d or ui d -ui d, indicating an inclusive range 

PRINTING 

pcnfsd supports a printing model based on the use of N FS to transfer the actual print data from the client to the server. The 
client system issues a pcnfsd_pr_init or pcn-fsd 2 _pr_init request, and the server returns the path to a spool directory that the 
client may use and which is exported by NFS. pcnfsd creates a subdirectory for each of its clients The parent directory is 
usually /usr/spooi/pcnfs and the subdirectory is the hostname of the client system. If you want to use a different parent 
directory, you should add a line of theform 

spooldir path 

to the/etc/pcnfsd.conf file. 

Oncea client has mounted the spool directory using N FS and has transferred print data to a file in this directory, it issues a 
pcnfsd_pr_start or pcnfsd 2 _pr_start request, pcnfsd handles this, and most other print-related requests, by constructing a 
command based on the printing services of the server operating system and executing the command using the identity of the 
PC user. Because this involves set-user-1 D privileges, pcnfsd must be run as root. 

Every print request from the client includes the name of the printer that is to be used. In Linux, this name corresponds to a 
printer definition in the/etc/printcap(5) database. If you want to define a non-standard way of processing print data, you 
should define a new printer and arrange for the client to print to this printer. There are two ways of setting up a new printer. 
The first involves the addition of an entry to /etc/printcap(5) and the creation of filters to perform the required processing. 
This is outside the scope of this discussion. In addition, pcnfsd indudesa mechanism by which you can define virtual 
printers known only to pcnfsd clients Each printer is defined by a line in the/etc/pcnfsd.conf file of thefollowing form: 

printer name alias-for command 

name is the name of the printer you want to define, a i as- for isthenameof a "real" printer that corresponds to this printer. 
For example, a request to display the queue for name is translated into the corresponding request for the printer a i i as-f or . If 
you have defined a printer in such a way that there is no "real" printer to which it corresponds use a single - for thisfield. 
(See thedefinition of the printer test for an example.) command isa command that will be executed whenever a file is printed 
on name. This command isexecuted by theshell at / bin/sh using the -c option. For complex operations, you should 
construct an executable shell program and invoke that in command. 

C onsider the following sample /etc/pcnf sd. conf file: 

printer rotated lw /usr/local/bin/enscript -2r $FILE 
printer test - /usr/bin/cp $FILE/usr/tmp/$HOST$USER 

If a client system prints a job on the printer rotated, the utility enscript is invoked to pre-process thefile $file. In this case, 
the -2r option causes the file to be printed in two-column rotated format on the default PostScript printer. If the client 
requests a list of the print queue for the printer rotated, the pcnfsd daemon translates this into a request for a listing for the 
printer iw. 

The printer test is used only fortesting. Any file sent to this printer iscopied into /usr/tmp. Any request to list the queue, 
check the status, and so on of printer test isrqected because the a i i as-f or is specified as-. 



plipconfig 


RECONFIGURATION 

pent sd detects when printers are added or deleted and rebuilds its list of valid printers T o do this, it checks the modification 
time of /etc/printcap. However, it does not monitor thefile/etc/pcnfsd.cont for updates if you change thisfile, it isstill 
necessary to kill and restart pent sd so the changes can take effect. 

FILE 

/etc/pcnfsd.conf 

SEE ALSO 

lpr(l), lprm(l), lpc(8), lpq(l) 

25 Junel995 


plipconfig 

plipconfig— Fine-tune PLIP device parameters 

SYNOPSIS 

plipconfig i nterface 

plipconfig interface [nibble NN] [trigger NN] [unit NN] 

DESCRIPTION 

plipconfig isusedto improvePUP performance by changing the default timing parameters used by the PLIP protocol. 
Results are dependent on the parallel port hardware, cable and the CPU speed of each machine on each end of the PLIP 
link. 

If the single i nt erf ace argument is given, plipconfig displays the status of the given interface only. Otherwise it tries to set 
the options 

OPTIONS 

nibble nn Sets the nibble wait value in microseconds. D efault issooe. 

trigger nn Sets the trigger wait value in microseconds. D efault issoo. 

unit nn Sets the number of units of delay. Default is i. 

In some cases, PLIP speed can be improved by lowering the default values Values that are too low might cause excess use of 
CPU, poor interrupt response time resulting in serial ports dropping characters, or in dropping PLIP packets Changing the 
plip MTU can also affect PLIP speed. 

SEE ALSO 

ifconfig(8) 

BUGS 

N one so far. 

AUTHOR 

John Paul Morrison (jmorriso@bogomips.ee.ubc.ca, ve7jpm@ve7jpm.ampr.org) 


1 July 1994 
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ping 

ping— Send ICMP echo_request packets to network hosts. 

SYNOPSIS 

/etc/ping [ -r ][-v ] host [ packets! z e ] [count ] 

DESCRIPTION 

T he D AR PA I nternet is a large and complex aggregation of network hardware, connected together by gateways. T racking a 
single-point hardwareor software failure can often be difficult. Ping utilizes the 1C M P protocol's mandatory echo_request 
datagram to elicit an IC M P echo_response from a host or gateway. echo_request datagrams ("pings") have an IP and IC M P 
header, followed by a struct timevai and then an arbitrary number of "pad" bytes used to fill out the packet. D efault 
datagram length is 64 bytes, but this may be changed using the command-line option. Other options are 
-r Bypass the normal routing tables and send directly to a host on an attached network. If 

the host is not on a directly attached network, an error is returned. This option can be 
used to ping a local host through an interface that has no route through it (for example 
after the interface wasdropped by routed(8C)). 

-v Verbose output. ICMP packets other than echo_response that are received are listed. 

W hen using ping for fault isolation, it should first be run on the local host to verify that the local network interface is up and 
running. Then, hosts and gateways further away should be pinged. Ping sends one datagram per second and prints one line 
of output for every echo_response returned. No output is produced if there is no response If an optional count is given, only 
that number of requests is sent. Round-trip times and packet-loss statistics are computed. W hen all responses have been 
received or the program times out (with a count specified), or if the program is terminated with a sigint, a brief summary is 
displayed. 

This program is intended forusein network testing, measurement, and management. It should be used primarily for manual 
fault isolation. Because of the load it could impose on the network, it is unwise to use ping during normal operations or from 
automated scripts. 

AUTHOR 

M ikeM uuss 

SEE ALSO 

netstat(l), ifconfig(8) 

19 September 1988 


portmap 

portmap— D ARPA port to RPC program number mapper. 

SYNOPSIS 

portmap [-d] 

DESCRIPTION 

portmap is a server that converts RPC program numbersinto DARPA protocol portnumbers It must be running in order to 
make RPC calls. 

When an RPC server isstarted, it tells portmap what port number it is listening to and what RPC program numbers it is 
prepared to serve When a client wants to make an RPC call to a given program number, it first contacts portmap on the 
server machine to determine the port number where RPC packets should be sent. 



portmap must be started before any RPC servers areinvoked. 

Usually, portmap forks and dissociates itself from theterminal like any other daemon. Portmap then logs errors using 
syslog(3). 

Option available 

-d (debug) prevents portmap from running asa daemon and causes errors and debugging information to be printed to the 
standard error output. 

SEE ALSO 

inetd.conf(5), rpcinfo(8), inetd(8) 

BUGS 

If portmap crashes, all servers must be restarted. 

HISTORY 

The portmap command appeared in BSD 4.3. 

BSD 4.3,16 M arch 1991 


powerd 

powerd— M onitor a serial line connected to a U PS. 

SYNOPSIS 

/etc/powerd seri al-device 

DESCRIPTION 

powerd isadaemon process that sits in the background and monitors the state of theDCD line of the serial device. It is 
meant that this line isconnected to a U PS (U ninterruptible Power Supply) so that it knows about the state of the U PS. As 
soon as powerd senses that the power isfailing (it sees that DCD goes low) it notifies init(8) and imt executes the powerwait 
and powertaii entries. If powerd senses that the power has been restored, it notifies imt again and imt executes the 
powerokwait entries. 

ARGUMENTS 

serial-devi ce Someserial port that is not being used by some other device and does not 

share an interrupt with any other serial port. 


DIAGNOSTICS 

powerd regularly checks the D SR line to see if it'shigh. DSR should be directly connected to DTR and powerd keeps that line 
high, so if D SR is low, something is wrong with the connection, powerd notifies you about thisfact every two minutes. When 
it sees that the connection is restored, it will say so. 

IMPLEMENTATION 

It's pretty simple to connect your U PS to the Linux machine. T he steps are easy: 

1. M ake sure you have an UPS with a simple rel aisoutput: it should close its connections (make) if the power is gone, and 
it should open its connections (break) if the power is good. 

2. Buy a serial plug. Connect the DTR line to the DSR line directly. Connect the DTR line and theDCD line with a 10 
kilo ohm resistor. Connecttherelais-outputoftheUPStoGROUN D and theDCD line If you don't know what pins 
D SR, DT R, D C D and G RO U N D are you can always ask at the store where you bought the plug. 

3. You’re all set. 
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BUGS 

W ell, it's not a real bug but powerd should be able to do a broadcast or something on the Ethernet in case more Linux-boxes 
are connected to the same U PS and only one of them isconnected to the U PS status line. 

SEE ALSO 

shutdown(8), init(8), inittab(5) 

AUTHOR 

M iquel van Smoorenburg (miquels@drinkel.nl.mugnet.org) 

14 February 1994 


PPPd 

pppd— Point-to-Point Protocol daemon. 

SYNOPSIS 

pppd [ 11 y _ n a me ] [s peed ] [opti 0 n s ] 


DESCRIPTION 

The Point-to-Point Protocol (PPP) provides a method for transmitting datagrams over serial point-to-point links. PPP is 
composed of three parts a method for encapsulating datagramsover serial links an extensible Link Control Protocol (LCP), 
and a family of Network Control Protocols (N CP) for establishing and configuring different network-layer protocols 
The encapsulation scheme is provided by driver code in the kernel, pppd provides the basic LCP, authentication support, and 
an NCP for establishing and configuring the Internet Protocol (IP) (called the IP Control Protocol, IPCP). 


FREQUENTLY USED OPTIONS 

tty. name Communicate over the named device. The string /dev/ is prepended if necessary. If no 

device name isgiven, or if the name of the controlling terminal isgiven, pppd uses the 
controlling terminal and does not fork to put itself in the background, 
speed Sdt the baud rate to speed (a decimal number). On systems such as 4.4BSD and 

NetBSD, any speed can be specified. 0 ther systems (such as SunO S) allow only a 
limited sdt of speeds 

asyncmap map Set the async character map to map. This map describes which control characters cannot 

be successfully received over the serial line pppd asks the peer to send these characters as 
a 2-byte escape sequence. The argument is a 32-bit hex number with each bit represent¬ 
ing a character to escape Bit 0 (00000001) represents the character 0x00; bit 31 (80000000) 
represents the character 0xi t or \ If multiple asyncmap optionsare given, the values are 
oRed together. If no asyncmap option isgiven, no async character map is negotiated for 
the receive direction; the peer should then escape all control characters 
auth Require the peer to authenticate itself before allowing network packetsto be sent or 

recaved. 


connect p U se the executable or shell command specified by p to set up the serial line. Thisscript 

typically uses the chat(8) program to dial the modem and start the remote PPP session, 
crtscts Use hardware flow control (that is RTS/CTS) to control the flow of data on the serial 

port. If neither the crtscts nor the -crtscts option isgiven, the hardware flow control 
setting for the serial port is left unchanged. 

defauitroute Add a default route to the system routing tables using the peer as the gateway, when 

IPCP negotiation is successfully completed. Thisentry is removed when thePPP 
connection is broken. 



pppd 


escape xx ,yy,.., 


file f 


lock 


netmask n 


OPTIONS 

local IP a d d r ess: 


Run the executable or shell command specified by p after pppd has terminated the link. 
This script could, for example, issue commands to the modem to cause it to hang up if 
hardware modem control signals were not available. 

Specifies that certain characters should be escaped on transmission (regardlessof whether 
the peer requests them to be escaped with its async control character map). The 
characters to be escaped are specified as a list of hex numbers separated by commas 
Note that almost any character can be specified for the escape option, unlike the 
asyncmap option, which only allows control characters to be specified. The characters 
that cannot be escaped are those with hex values 0x20 - ox3f oruxse. 

Read optionsfrom filef (theformatisdescribed later). 

Specifies that pppd should create a U U C P-style lock fi le for the serial device to ensure 
exclusive access to the device. 

Set the M RU (M aximum Receive Unit) value ton for negotiation, pppd asks the peer to 
send packets of no morethann bytes The minimum M RU value is 128. The default 
M RU value is 1500. A valueof 296 is recommended for slow links (40 bytes for TCP/IP 
header plus 256 bytes of data). 

SdttheMTU (M aximum T ransmit Unit) value to n. Unless the peer requests a smaller 
value via MRU negotiation, pppd requests that the kernel networking code send data 
packets of no more than n bytes through the PPP network interface 
Set the interface netmask to n, a 32-bit netmask in decimal dot notation (such as 
255 . 255 . 255 . 0 ). If thisoption isgiven, the value specified isoRed with thedefault 
ndtmask. Thedefault netmask ischosen based on the negotiated remotelP address; it is 
the appropriate network mask for the class of the remote IP address oRed with the 
netmasksfor any non-point-to-point network interfaces in the system that are on the 
same network. 

Enables the passive option in the LCP. With thisoption, pppd attempts to initiate a 
connection; if no reply is received from the peer, pppd then waits passively for a valid 
LCP packet from the peer (instead of exiting as it does without this option). 

With thisoption, pppd does not transmit LCP packets to initiate a connection until a 
valid LCP packet is received from the peer (as for the passive option with ancient 
versions of pppd). 


remote ip address Set the local and/or remote i nterface IP addresses Either onemay be 

omitted. T he IP addresses can be specified with a host name or in decimal 
dot notation (such as 150.234.56.7s). Thedefault local addressisthe 
(first) IP address of the system (unlessthe noipdefauit option isgiven). 
The remote address is obtained from the peer if not specified in any 
option. Thus, in simple cases, thisoption isnot required. If a local and/or 
remote IP address isspecified with this option, pppd does not accept a 
different value from the peer in the I PC P negotiation, unless the 
ipcp-accept-iocai and/or ipcp-accept-remote optionsare given. 

Disable Address/Control compression negotiation (use default, address^ 
control field compression disabled). 

Don't request or allow negotiation of any options for LCP and IPCP (use 
default values). 

Disable asyncmap negotiation (use the default asyncmap; that is, escape all 
control characters). 

Same as asyncmap n. 
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bsdcomp 


-bsdcomp 

chap-max-challenge n 
chap-restart n 


-defaultroute 


-detach 


+ip-protocol 
-ip-protocol 

+ipx-protocol 


Request that the peer compress packets that it sends, using the 
BSD-Compress scheme with amaximum code size of nr bits and agree to 
compress packetssentto the peer withamaximum codesize of nt bits If 
nt is not specified, it defaults to the value given for nr . Values in the range 
9 to is may be used for nr and nt ; larger values give better compression 
but consume more kernel memory for compression dictionaries 
Alternatively, a value of 0 for nr or nt disables compression in the 
corresponding direction. 

D i sables compression; pppd does not request or agree to compress packets 
using the BSD-Compress scheme. 

Require the peer to authenticate itself using C H AP (C ryptographic 
H andshakeAuthentication Protocol) authentication. 

Don't agree to authenticate using CHAP. 

If this option is given, pppd rechallenges the peer every n seconds 

Set the maximum number of CHAP challenge transmissions to u (default 

is 10). 

SdttheCHAP restart interval (retransmission timeout for challenges) ton 
seconds (default is 3). 

D isable hardware flow control (RTS/CTS) on the serial port. If neither 
the crtscts nor the -crtscts option is given, the hardware flow control 
setting for the serial port is left unchanged. 

I ncrease debugging level (same as the debug option). 

Increase debugging level (same as-d). Ifthisoption isgiven, pppd logs the 
contents of all control packets sent or received in a readable form. The 
packets are logged through sysiog with facility daemon and level debug. 
This information can bedirected to afileby setting up /etc/sysiog.conf 
appropriately (see sysiog.cont(5)). 

Disable the defaultroute option. The system administrator who wants to 
prevent users from creating default routes with pppd can do so by placing 
thisoption in the /etc/ppp/options file 

Don't fork to become a background process (otherwise pppd will do so if 
a serial device other than its controlling terminal is specified). 

Thisoption sets the IP address or addressesfor the Domain N ame Server. 
It is used by M icrosoft W indows clients The primary DNS address is 
specified by the first instance of the dns-addr option. The secondary is 
specified by the second instance. 

Append the domain named tothelocal hostname for authentication 
purposes. For example if gethost-named returnsthenameporsche, but 
thefully qualified domain nameisporsche.Quotron.coM, you use the 
domain option to set the domain name to Quotron.coM. 

Disable IP address negotiation. Ifthisoption is used, the remote IP 
address must be specified with an option on the command line or in an 
optionsfile 

Enablethe I PC P and IP protocols. This is the default condition. This 
option isonly needed if the default setting is-ip-protocoi. 

Disable the I PC P and IP protocols This should only be used if you know 
you are using a client that only understands IPX and you don't want to 
confuse the client with the I PC P protocol. 

Enablethe IPXCP and IPX protocols. This is the default condition if 
your kernel supportsIPX. Thisoption isonly needed if the default setting 
is -ipx-protocoi. If your kernel does not support IPX, this option has no 
effect. 
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-ipx-protocol 

ipcp-accept-local 
ipcp-accept-remote 
ipcp-max-configure 
ipcp-max-failure n 
ipcp-max-terminate 
ipcp-restart n 
ipparam string 

ipx-network n 




ipxcp-accept-local 


ipxcp-accept-network 


ipxcp-accept-remote 


ipxcp-max-configure n 


Disable the IPXCP and IPX protocols This should only be used if you 
know you are using a client that only understands IP and you don't want 
to confuse the client with the IPXC P protocol. 

With this option, pppd accepts the peer's idea of a local IP address even if 
the local IP address was specified in an option. 

W i th this option, pppd accepts the peer's idea of its (remote) IP address 
even if the remote IP address was specified in an option. 

Sdt the maximum number of IPCP configure-request transmissions to n 
(default is 10). 

set the maximum number of IPCP configure-N AKs returned before 
starting to send configure-Rgects instead to n (default is 10). 
set the maximum number of I PC P term in ate-request transmissions to n 
(default is 3). 

Set the I PC P restart interval (retransmission timeout) to n seconds 
(default is 3). 

Provides an extra parameter to the ip-up and ip-down scripts. If this 
option isgiven, the s t r i ng supplied isgiven as the sixth parameter to 
those scripts. 

set the IPX network number in the I PXC P configure request frame to n. 
There is no valid default. If this option is not specified, the network 
number is obtai ned from the peer. If the peer does not have the network 
number, the IPX protocol is not started. This is a hexadecimal number 
and is entered without any leading sequence such asox. It is related to the 
ipxcp-accept-network option. 

Set the I PX node numbers. The two node numbers are separated from 
each other with a colon character. The first number n is the local node 
number. The second number misthe peer's node number. Each node 
number is a hexadecimal number to the maximum often significant 
digits The node numbers on theipx-ndtwork must be unique. There is 
no valid default. If this option is not specified, the node number is 
obtained from the peer. Thisoption is a related to the ipxcp-accept-iocai 
and ipxcp-accept-remote options 

Sdt the name of the router. This isa string and is sent to the peer as 
information data. 

Sdt the routing protocol to be received by thisoption. M ore than one 
instance of ipx-routing may be specified. The none option (0) maybe 
specified as the only instance of ipx- routing. The values are 0 for none, 2 
for RIP/SAP, and 4forNLSP. 

Accept the peer's N AK for the node number specified in the ipx-node 
option. If a node number was specified and it is nonzero, the default isto 
insist that the value be used. If you include this option, you permit the 
peer to override the entry of the node number. 

Accept the peer's N AK for the network number specified in the ipx- 
network option. If a network number was specified and it is nonzero, the 
default isto insist that the value be used. If you include thisoption, you 
permit the peer to override theentry of the node number. 

U se the peer's network number specified in the configure request frame. 

If a node number was specified for the peer and thisoption was not 
specified, the peer is forced to use the value that you specified, 
set the maximum number of IPXCP configure request frames that the 
system sends to n. The default is 10. 
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ipxcp-max-failure n 
ipxcp-max-terminate n 


kdebug n 




)-failure n 


lcp-echo-interval n 


lcp-max-configure n 
lcp-max-failure n 
lcp-max-terminate n 

modem 


Sdt the maximum number of IPXCP NAK frames that the local system 
sends before it rqects the options. The default value is3. 

Set the maximum number of IPXC P terminate request frames before the 
local system considers that the peer is not listening to them. T he default 
value is 3. 

Enable debugging codein the kernel-level PPP driver. The argument n is 
a number that is the sum of thefollowing values: i to enable general 
debug messages, 2 to request that the contents of reca ved packets be 
printed, and 4 to request that the contents of transmitted packets be 
printed. 

If thisoption is given, pppd presumes the peer is dead if n LCP echo- 
requests are sent without receiving a valid LCP echo-reply. If this 
happens, pppd terminates the connection. Use of thisoption requiresa 
nonzero value for the icp-echo-intervai parameter. Thisoption can be 
used to enable pppd to terminate after the physical connection has been 
broken (for example the modem has hung up) in situations where no 
hardware modem control lines are available 
If thisoption isgiven, pppdsendsan LCP echo-request frame to the peer 
every n seconds Under Linux, the echo-request issentwhen no packets 
are received from the peer for n seconds. U sual ly, the peer should respond 
to the echo-request by sending an echo-reply. Thisoption can be used 
with the icp-echo-faiiure option to detect that the peer is no longer 
connected. 

Set the maximum number of LCP configure-request transmissions ton 
(default is 10). 

Set the maximum number of LCP configure-N AKs returned before 
starting to send configure-Rqects instead to n (default is 10). 

Set the maximum number of LC P terminate-request transmissionsto n 
(default is 3). 

Set the LC P restart interval (retransmission timeout) to n seconds (default 

iS3). 

Don't use the modem control lines. With thisoption, pppd ignores the 
state of the C D (C arrier D etect) signal from the modem and does not 
changethestateof the DTR (DataTerminal Ready) signal. 

Use the system password database for authenticating the peer using PAP, 
and record the user in the system wtmp file. 

Use the modem control lines Thisoption is the default. With this 
option, pppd waits for the CD (Carrier Detect) signal from the modem to 
be asserted when opening the serial device (unless a connect script is 
specified), and it drops the DTR (DataTerminal Ready) signal briefly 
when theconnection is terminated and before executing the connect 
script. On Ultrix, thisoption implies hardware flow control, as for the 
crtscts option. 

Disable magic number negotiation. With thisoption, pppd cannot detect 
alooped-backline 

D isable MRU (M aximumReceiveUnit) negotiation. With thisoption, 

pppd uses the default M RU value of 1500 bytes 

Set the name of the local system for authentication purposes to n. 

Disables the default behavior when no local IP address is specified, which 
is to determine (if possible) the local IP address from the hostname With 
thisoption, the peer must supply the local IP address during I PC P 
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+pap 

■pap 

papcrypt 

pap-max-authreq n 

pap-timeout n 

persist 

predlcomp 

-predlcomp 

proxyarp 

■proxyarp 

remotename ti 


usehostname 


-vjccomp 




negotiation (unless it specified explicitly on the command line or in an 
optionsfile). 

Same as the passive option. 

Require the peer to authenticate itself using PAP. 

Don't agree to authenticate using PAP. 

Indicates that all secrets i n the/etc/ppp/pap-secrets file, which are used 
for checking the identity of the peer, are encrypted, and thus pppd should 
not accept a password (before encryption) that is identical to the secret 
from the /etc/ppp/pap-secrets file. 

Set the maximum number of PAP authenticate-request transmissions to n 
(default is 10). 

Set the PAP restart interval (retransmission timeout) to n seconds (default 

iS3). 

Set the maximum time that pppd waits for the peer to authenticate itself 
with PAP to n seconds (0 means no limit). 

Disable protocol field compression negotiation (use default, protocol field 
compression disabled). 

D 0 not exit after a connection isterminated; instead, try to reopen the 
connection. 

Attempt to request that the peer send the local system frames, which have 
been compressed by the Predictor-1 compression. The compression 
protocolsmust beloaded orthisoption isignored. 

D 0 not accept Predictor-1 compression, even if the peer wants to send 
thistype of compression and support has been defined in the kernel. 

Add an entry to thissystem'sARP (Address Resolution Protocol) table 
with the IP address of the peer and the Ethernet addressof this system. 
Disable the proxyarp option. The system administrator who wants to 
prevent users from creating proxy ARP entries with pppd can do so by 
placing thisoption in the /etc/ppp/options file. 

Set the assumed name of the remote system for authentication purposes 
ton. 

Agree to authenticate using PAP (Password Authentication Protocol) if 
requested bythepeer and use the data in file p for the user and password 
to send to the peer. The file contains the remote username, followed by a 
newline followed by the remote password, followed by a newline This 
option is obsolescent. 

Enforcetheuseof the hostname as the name of the local system for 
authentication purposes (overrides the name option). 

Set the username to use for authenticating this machine with the peer 
using PAP to u. 

Disable negotiation of Van J acobson-style TCP/IP header compression 
(use default, no compression). 

Disable the connection-1 D compression option in V an J acobson style 
TCP/IP header compression. With thisoption, pppd does not omit the 
connection-ID bytefromVan J acobson compressed TC P/I P headers or 
ask the peer to do so. 

Sdts the number of connection slots to be used by theVan Jacobson 
TCP/IP header compression and decompression code to n, which must be 
between 2 and ie (inclusive). 
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xonxoff Use software flow control (XON/XOFF) to control theflowofdataon 

theserial port. This option isonly implemented on Linux systems at 
present. 

OPTIONS FILES 

Options can betaken from files as well asthe command line, pppd readsoptionsfromthefiles/etc/ppp/optionsand"/.ppprc 
before looking at thecommand line. An options file isparsed into a seriesof words, delimited by whitespace. Whitespace can 
be included in a word by enclosing the word in quotes (■). A backslash (\) quotes the following character. A hash (#) startsa 
comment, which continuesuntil the end of the line. 


AUTHENTICATION 

pppd provides system administrators with sufficient access control so that PPP access to a server machine can be provided to 
legitimate users without fear of compromising the security of the server or the network it'son. In part, this is provided by the 
/etc/ppp/options file, where the administrator can place options to require authentication whenever pppd is run, and in part 
by the PAP and C H AP secrets files, where the administrator can restrict the set of IP addresses that individual users can use. 
The default behavior of pppd isto agree to authenticate if requested and to not require authentication from the peer. 

Flowever, pppd does not agree to authenticate itself with a particular protocol if it has no secrets that can be used to do so. 
Authentication is based on secrets, which are selected from secrets files(/etc/ppp/pap-secrets for PAP, 

/etc/ppp/chap-secrets for CHAP). Both secrets files have the same format, and both can store secrdts for several combina¬ 
tions of server (authenticating peer) and client (peer being authenticated). N otethat pppd can be both a server and client and 
that different protocols can be used in the two directions if desired. 

A secrets file is parsed into words as for an optionsfile A secret is specified by a line containing at least three words, in the 
order client name, server name and secret. Any following words on the same line are taken to be a list of acceptable IP 
addressesfor that client. If there are only three words on the line, it is assumed that any IP address is okay; to disallow all IP 
addresses, use -. If the secret starts with an @, what follows is assumed to be the name of a file from which to read the secret. 

A * as the client or server name matches any name. W hen selecting a secret, pppd takes the best match—that is, the match 
with thefewest wildcards 


A secrets file contains both secrets for use in authenticating other hosts and secrets that you use for authenticating yourself to 
others Which secret to useischosen based on the names of the host (the local name) and its peer (the remote name). The 
local name is set as follows: 


If the usehostname option isgiven, 

If the name option isgiven 

If thelocal IP address is specified with a 

hostname 


T he local name is the hostname of this machine (with thedomain 
appended, if given). 

Use the argument of the first name option seen. 

Use that name Otherwise, use the hostname of this machine (with the 
domain appended, if given). 


W hen authenticating yourself using PAP, there isalso a username, which isthe local name by default, but can beset with the 
user option or the+ua option. 

The remote name is set as follows: 

If the remotename option isgiven Use the argument of the last remote-name option seen. 

If the remote IP address is specified with a Use that host name. Otherwise the remote name is the null 

hostname string"". 

Secrets are selected from the PAP secrets file as follows 

■ For authenticating the peer, look for a secret with client = username specified in the PAP authenticate-request and 
server = local name. 

■ For authenticating yourself to the peer, look for a secret with client =your username and server = remote name. 
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When authenticating the peer with PAP, a secret of 1111 matches any password supplied by the peer. If the password doesn't 
match thesecret, the password isencrypted using cryptf ) and checked against the secret again; thus secrets for authenticat¬ 
ing the peer can be stored in encrypted form. If thepapcrypt option isgiven, thefirst (unencrypted) comparison is omitted 
for better security. 

If thelogin option was specified, the username and password are also checked against the system password database. T hus, 
the system administrator can set up the pap-secrets file to allow PPP access only to certain users and to restrict the set of IP 
addresses that each user can use. Typically, when using the login option, thesecret in /etc/ppp/pap-secrets is 1 " 1 to avoid the 
need to have the same secret in two places 
Secrets are selected from theCH AP secrets file as follows: 

■ For authenticating the peer, look for a secret with client = name specified in theCH AP-Response message and server 
= local name 

■ For authenticating yourself to the peer, look for a secret with client = local name and server = name specified in the 
C FI AP-Challenge message 

Authentication must be satisfactorily completed before I PC P (or any other N dtwork Control Protocol) can be started. If 
authentication fails, pppd terminates the link (by closing LCP). If I PC P negotiates an unacceptable IP address for the remote 
host, IPCP is closed. IP packets can only be sent or received when I PC P isopen. 

In some cases, it is desirable to allow some hosts that can't authenticate themselves to connect and use one of a restricted set 
of IP addresses, even when the local host generally requires authentication. If the peer refuses to authenticate itself when 
requested, pppd takes that as equivalent to authenticating with PAP using the empty string for the username and password. 
Thus, by adding a line to the pap-secrets file, which specifies the empty string for the client and password, it is possible to 
allow restricted access to hosts that refuse to authenticate themselves 

ROUTING 

When IPCP negotiation is completed successfully, pppd informsthe kernel of the local and remotelP addressesforthePPP 
interface. This is sufficient to create a host route to the remote end of the link, which enables the peers to exchange IP 
packets Communication with other machines generally requires further modification to routing tables and/or ARP (Address 
Resolution Protocol) tables In some cases this is done automatically through the actionsof the routed or gated daemons 
but in most cases somefurther intervention is required. 

Sometimes it is desirable to add a default route through the remote host, as in the case of a machine whose only connection 
to the Internet is through the PPP interface Thedefauitroute option causes pppd to create such a default route when IPCP 
comes up and delete it when the link isterminated. 

In some cases, it is desirable to use proxy ARP— for example, on a server machine connected to a LAN —to allow other hosts 
to communicate with the remote host. Theproxyarp option causes pppd to look for a network interface on the same subnet as 
the remote host (an interface supporting broadcast and ARP, which is up and not a point-to-point or loopback interface). If 
found, pppd createsa permanent, published ARP entry with the IP address of the remote host and the hardware address of 
the network interfacefound. 

EXAMPLES 

In thesimplest case, you can connect the serial ports of two machines and issue a command like 

pppd /dev/ttya 9600 passive 

to each machine assumingthereisnogetty running on the serial ports If one machine has a getty running, you can use 
kermit or tip on the other machineto log in to thefirst machineand issue a command like 
pppd passive 

Then exit from the communications program (making sure the connection isn't dropped) and issue a command like 

pppd /dev/ttya 9600 
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The process of logging in to the other machine and starting pppd can be automated by using the connect option to run chat: 

pppd /dev/ttya 38400 connect 'chat .login:" "username" 

"Password:" "pass-word" "% " "exec pppd passive" 

(N ote however, that running chat like this leaves the password visible in the parameter list of pppd and chat.) 

If your serial connection is any more complicated than a piece of wire, you might need to arrange for some control characters 
to be escaped. In particular, it is often useful to escape XON ('DJandXOFF (''S), using asyncmap a0@00. If thepath 
includes a telnet, you probably should escape"] as well (asyncmap 20030000). If thepath includes an r login, you need to use 
the escape ft option on the end that is running the rlogin client because many rlogin implementationsarenot transparent; 
they remove the sequence (Oxff, Oxff, 0x73,0x73, followed by any 8 bytes) from the stream. 

DIAGNOSTICS 

M essages are sent to thesysiog daemon using thefacility log_daemon. (Thiscan be overridden by recompiling pppd with the 
macro log_ppp defined as the desired facility.) To see the error and debug messages, you need to edit your /etc/sysiog.cont 
file to direct the messages to the desired output device or file. 

The debug option causes the contents of all control packets sent or received to be logged-that is, all LCP, PAP, CHAP, or 
IPCP packets Thiscan be useful if thePPP negotiation does not succeed. If debugging is enabled at compile time the debug 
option also causes other debugging messages to be logged. 

Debugging can also be enabled or disabled by sending a sigusri to the pppd process. This signal acts as a toggle. 


/var/run/pppn .pid (BSD orLinux) Process-ID for pppd processon PPP interface unit n. 

/etc/ppp/pppn.pid (Others) 

/etc/ppp/ip-up A program or script that is executed when the link is available for sending and 

receiving IP packets (that is IPCP has come up). It isexecuted with the 
parameters i nt erf ace-name tty-device speed I ocal -1 P-address remote -1 P-address 
and with its standard input, output and error streams redirected to /dev/nuii. 
This program or script isexecuted with the same real and effective user- ID as 
pppd- that is at least the effective user-1 D and possibly the real user-1 D will be 
root. T his is so that it can be used to manipulate routes, run privileged daemons 
(such assend-mail), and so on. Becareful that the contents of the /etc/ppp/ip-up 
and /etc/ppp/ip-down scripts do not compromise your system's security, 
/etc/ppp/ip-down A program or script that isexecuted when the link isno longer available for 

sending and receiving IP packets This script can be used for undoing the effects 
of the /etc/ppp/ip-up script. It isinvoked with the same parameters as the ip-up 
script, and the same security considerations apply becauseit isexecuted with the 
same effecti ve and real user-1D s as pppd. 

/etc/ppp/ipx-up A program or script that isexecuted when the link is available for sending and 

receiving IPX packets (that is IPXCP has come up). It isexecuted with the 
parameters i nt erf ace-name tty-devi ce speed network-number I ocal -1PX- node- 
address remot e -1 PX- node- address I ocal ■I PX-routi ng-protocol remote-IPX- 

pi d and with its standard input, output, and error streams redirected to 

/dev/null. 

The 1 ocal -1 px-routi ng-protocol and remote-i px-routi ng-protocoi field maybe 
one of the following: 



pppiats 


/etc/ppp/ipx-down 


/etc/ppp/pap-secrets 

/etc/ppp/chap-secrets 

/etc/ppp/options 

~/.ppprc 

/etc/ppp/options.ttyname 


none to indicate that there is no routing protocol, rip to indicate that RIP/SAP 
should be used, nlsp to indicate that N ovell N LSP should be used, rip nlsp to 
indicate that both RIP/SAP and N LSP should be used. 

This program or script isexecuted with the same real and effective user-ID as 
pppd— that is, at least the effective user-1 D and possibly the real user-1 D will be 
root. This is so that it can be used to manipulate routes, run privileged daemons 
(such asripd), and so on. Be careful that the contents of the /etc/ppp/ipx-up and 
/etc/ppp/ipx-down scripts do not compromise your system's security. 

A program or script that isexecuted when the link is no longer available for 
sending and receiving IPX packets This script can be used for undoing the 
effects of the /etc/ppp/ipx-up script. It isinvoked with the same parameters as 
the ipx-up script, and the same security considerations apply because it is 
executed with the same effective and real user-1 Ds as pppd. 

Usernames passwords and IP addresses for PAP authentication. 

Names, secrets and IP addressesforCH AP authentication. 

System default optionsfor pppd, read before user default optionsor command- 
lineoptions. 

User default options read before command-line options 

System default optionsfor the serial port being used, read after command-line 

options 


SEE ALSO 

RFC 1144 

RFC 1321 
RFC 1332 
RFC 1334 
RFC 1548 
RFC 1549 


Jacobson, V. Compressing TCP/IP headersfor low-speed serial links February 
1990. 

Rivest, R. TheM D5 M essage-Digest Algorithm. April 1992. 

M cGregor, G. PPP Internet Protocol Control Protocol (IPCP). M ay 1992. 
Lloyd, B.; Simpson, W .A. PPP authentication protocols 1992 October. 
Simpson, W.A. ThePoint-to-Point Protocol (PPP). December 1993. 
Simpson, W.A. PPP in H DLC Framing. December 1993. 


NOTES 

T hefollowing signals have the specified effect when sent to the pppd process 

sigint, sigterm T hese signals cause pppd to terminate the link (by closing LCP), restore the serial 

de/ice settings and exit. 

sighup Thissignalcausespppdtoterminatethelink, restore the serial device settings and 

close the serial device. If the persist option has been specified, pppd tries to 
reopen the serial device and start another connection. Otherwise, pppd exits 

SIGUSR 2 Thissignal causes pppd to renegotiate compression. Thiscan be useful to re¬ 

enable compression after it has been disabled as a result of a fatal decompression 
error. W ith the BSD Compress scheme, fatal decompression errorsgenerally 
indicate a bug in one or another implementation. 

AUTHORS 

Drew Perkins, Brad Clements, Karl Fox, Greg Christy, Brad Parker, and Paul M ackerras (pauius@cs.anu.edu.au) 


pppstats 

pppstats— Print PPP statistics. 
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SYNOPSIS 

pppstats [ -V ][-r ][-c ][-i secs ] [uni t # ] 

DESCRIPTION 

pppstats prints PPP-related statistics 

The -v flag causes pppstats to display additional statistics such as the number of packets tossed (that is, which the VJ TC P 
header decompression code rqected). 

The -r flag causes pppstats to display the overall packet compression rate. The rate value is between 0 and 1 , with 0 meaning 
thatthedata is incompressible. 

T he -c flag is used to specify an alternate display mode that shows packet compression statistics: the number of packets and 
bytes uncompressed (that is, before compression or after decompression), compressed, and incompressible (packets that did 
not shrink on compression and were transmitted uncompressed), and the recent compression rate. This rate reflects the 
recent performance of the compression code rather than the overall rate the code compression was enabled. 

The -i flag is used to specify the interval between printouts. The default is 5 seconds 
unit# specifies which interface to use for gathering statistics. 

2 May 1995 


prunehistory 

prunehistory— Remove filenames from Usenet history file 

SYNOPSIS 

prunehistory [ -f filename ] [-p ] [input ] 

DESCRIPTION 

prunehistory modifies the history(5) text file to remove a set of filenames from it. The filenames are removed by overwriting 
them with spaces so that the size and position of any following entries do not change 

prunehistory reads the named input file or standard input if no file isgiven. T he input istaken asa set of lines. Blank lines 
and lines starting with a number sign (#) are ignored. All other lines should consist of a M essage-ID followed by zero or more 
filenames prunehistory usually complains about lines that do not follow thisformat. If the -p flag is used, then the program 
silently prints any invalid lines on its standard output. (Blank lines and comment lines are also passed through.) This can be 
useful when prunehistory isused as a filter for other programs such as reap. 

The M essage-l D is used as the dbz(3) key to get an offset into the text file If no filenames are mentioned on the input line, 
then all filenames in the text are removed. If any filenames are mentioned, they are converted into the history file notation. If 
they appear in the line for the specified M essage-ID, they are removed. 

T he default name of the history file is /news/iib/history; to specify a different name use the -t flag. 

Because innd(8) only appends to the text file prunehistory does not need to have any interaction with it. 

It is a good idea to delete purged entries and rebuild thedbz database every so often by using a script such as the following: 
ctlinnd throttle "Rebuilding history database" 
cd /news/lib 

printf "%s\t%s\t%s",$1,$2,$3; 
printf " %s", $i; 

}' <history >history.n 
if makehistory -r -f history.n ; then 



quotacheck 


mv history.n history 
mv history.n.pag history.pag 
mv history.n.dir history.dir 

echo 'Problem rebuilding history; old file not replaced' 
fi 

ctlinnd go "Rebuilding history database" 

N otethat this keeps no record of expired articles 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

dbz(3), history(5), innd(8) 

quotacheck 

quotacheck— Scan a filesystem for disk usages 

SYNOPSIS 

quotacheck [-g] [ -u] [-v] -a 
quotacheck [-g] [-u] [- v] filesys ... 

DESCRIPTION 

quotacheck performs a filesystem scan for usage of files and directories, used by either user or group. The output isthequota 
file for the corresponding filesystem. Bydefault, the namesfor these files are 
A user scan quota.user 

A group scan quota.group 

T he resulting file consists of a struct dqbik for each possible ID up to the highest existing U ID orGID and containsthe 
values for the disk file and block usage and possibly excess time for these values (For definitionsof struct dqbik, see 

linux/quota.h.) 

quotacheck should be run each time the system boots and mounts non-valid filesystems This is most likely to happen after a 
system crash. 

The speed of the scan decreases with the amount of directories increasing. The time needed doubles when disk usageis 
doubled as well. A 100M B partition used for 94 percent is scanned in one minute; the same partition used for 50 percent is 
done in 25 seconds. 

OPTIONS 

-v This way, the program will give some useful information about what it isdoing, plus 

some fancy stuff. 

-d This means debug. It will result in a lot of information that can be used in debugging 

the program. The output is very verbose and the scan will not be fast. 

-u Thisflag tells the program to scan thedisk and to count the files and directories used by 

a certain U ID. Thisisthedefault action. 

-g This flag forces the program to count the files and directories used by a certain GID. 

NOTE 

checkquota should only be run as superuser. N on-privileged users are presumably not allowed to read all the directories on 
the given filesystem. 
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SEE ALSO 

quota(l), quotactl(2), fstab(5), quotaon(8), quotaoff(8), edquota(8), repquota(8), fsck(8), efsck(8), e2fsck(8), xfsck(8) 

FILES 



AUTHOR 

Edvard Tuinder (v892231@si.hhs.nl, etuinder@delirium.nl.mugnet.org), M arCO Van Wieringen (v892273@si.hhs.nl, 
mvw@mcs.nl.mugnet.org). 

21 August 1993 

quotaon,quotaoff 

quotaon, quotaoff— T urn filesystem quotas on and off. 

SYNOPSIS 



DESCRIPTION 

quotaon announces to the system that disk quotas should be enabled on one or more filesystems. Thefilesystem quota files 
must be present in the root directory of the specified filesystem and be named quota, user for user quota or quota, group for 
group quota. 

quotaoff announces to the system that filesystems specified should have any disk quotas turned off. 

OPTIONS 

quotaon 

-a All filesystems in /etc/fstab marked read-write with quotas will have their quotas 

turned on. This is usually used at boot time to enable quotas. 

-v D isplay a message for each filesystem where quotas are turned on. 

-u Manipulate user quotas T his isthe default. 

-g M anipulate group quotas 

quotaoff 

-a Forceall filesystems in /etc/fstab to havetheirquotasdisabled. 

-v Display a message for each filesystem affected. 

-u Manipulate user quotas T his isthe default. 

-g M anipulate group quotas 

FILES 

quota, user User quota file at the filesystem root 

quota.group Group quota file at thefilesystem root 

/etc/fstab Default filesystems 





rdev 


SEE ALSO 

quotactl(2), fstab(5) 


8Junel993 


rarp 

rarp— M anipulate the system RARP table 

SYNOPSIS 

rarp [ -v] [-t type] -a [hostname] 

rarp [-v] -d host name ... 

rarp [-v] [-t type] -s hostname hv/.addr 


DESCRIPTION 

rarp manipulates the kernel's RARP table in various ways The primary options are clearing an address mapping entry and 
manually setting up one For debugging purposes, the rarp program also allows a complete dump of theRARP table. 


OPTIONS 


-a [tioStname ] 


FILES 

/proc/net/rarp 


Tell the user what is going on by being verbose 

When setting or reading theRARP table, this optional parameter tells rarp which class 
of entries it should check for. The default value of this parameter is ether (hardware 
code 0x01 for IEEE 802.3 10M bps Ethernet). Other values might include network 
technologies such asAX.25 (ax25). 

Shows the entries of the specified hosts. If the host name parameter is not used, all entries 
are displayed. 

Remove the entries of the specified host. This can be used if the indicated host is 
brought down, for example 

Create an RARP address mapping entry for host host name with hardware address set to 
hw.addr class, but for most classes, you can assume that the usual presentation can be 
used. For the Ethernet class, this is 6 bytes in hexadecimal, separated by colons. 


AUTHORS 

ROSSD . M artin (martin@trcsun3.eas.asu.edu), Fred N . Van Kempen (waltje@uwalt.nl.mugnet.org). 


11Junel994 


rdev 

rdev— Q uery/set image root device, swap device, RAM disk size, or video mode 

SYNOPSIS 

rdev [ -rsvh ] [ -o offset ] [image [value [offset ]]] 
rdev [ -o offset ] [image [ root_device [ offset ]]] 
swapdev [ -o offset ] [ i ma g e [ swap.device [ offset ]]] 

ramsize [ -o offset ][ i ma g e [size [ offset ]]] 

vidmode [ -o offset ] [ i ma g e [ mode [ offset ]]] 

rootflags [ -o offset ] [image [flags [offset ]]] 
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DESCRIPTION 

With no arguments, rdev outputs an /e tc/mtab linefor the current root filesystem. With no arguments, swapdev, ramsize, 
vidmode, and rootfiags print usage information. 

I n a bootable image for the Linux kernel, there are several pairs of bytes that specify the root device, the video mode the size 
of the RAM disk, and the avap device These pairsof bytes, by default, begin at offset 504 (decimal) in the kernel image: 

498 Rootfiags 
(500 and 502 Reserved) 

504 RAM Disk Size 
506VGA Mode 
508 Root Device 
(510 Boot Signature) 
rdev changes these values. 

Typical valuesfor the image parameter, which isa bootable Linux kernel image, are as follows 
/vmlinux.test 


/dev/fd0 

/dev/fdl 

When using the rdev or swapdev commands, the root device or swap device parameter are as follows: 

/dev/hda[1-8] 

/dev/hdb[1-8] 

/dev/sda[1-8] 

/dev/sdb[1-8] 

Forthe ramsize command, the size parameter specifies the size of the RAM disk in kilobytes 

For the rootfiags command, thef i ags parameter contains extra information used when mounting root. Currently, the only 
effect of these flags is to force the kernel to mount the root filesystem in read-only mode iff i ags is nonzero. 

For the vidmode command, the mode parameter specifies thevideo mode: 

-3 Prompt 

-2 Extended VGA 

■ i N ormal VGA 

0 As if 0 was pressed at the prompt 

1 As if i was pressed at the prompt 

2 As if 2 was pressed at the prompt 

n As if n was pressed at the prompt 

If the value is not specified, the image is exami ned to determine the current settings. 

OPTIONS 

-s Causes rdev to act like swapdev. 

-r Causes rdev to act like ramsize. 

-R Causes rdev to act like rootfiags. 

- v C auses rdev to act I i ke vidmode. 

-h Provides help. 



renice 


BUGS 

For historical reasons, there are two methodsfor specifying alternative values for theoffset. 

The user interface is cumbersome, non-intuitive, and should probably be rewritten from scratch, allowing multiple kernel 
image parameters to be changed or examined with a single command. 

If LILO is used, rdev is no longer needed for setting the root de/ice and the VGA mode because the parameters that rdev 
modifies can be set from the LILO prompt during a boot. Flowever, rdev isstill needed at this time for setting the RAM disk 
size. U sers are encouraged to find the LILO documentation for more information and to use LILO when booting their 
systems 

AUTHORS 

Originally by Werner Almesberger (aimesber@nessie.cs.id.ethz.ch). M odified by Peter M acDonald 
(pmacdona@san;j uan .UVic.CA). rootflags Support added by Stephen Tweedie (sct@dcs.ed.ac.uk). 

Linux0.99, 20 N member 1993 


renice 

renice— Alter priority of running processes 

SYNOPSIS 

renice priority [[-p] pi d ...] [[ -g] pgrp ...] [[-u] user ...] 

DESCRIPTION 

renice alters the scheduling priority of one or more running processes. Thefollowing "who" parameters are interpreted as 
processIDs process group IDs or user names, reniceing a process group causes all processes in the process group to have 
their scheduling priority altered, reniceing a user causes all processes owned by the user to have their scheduling priority 
altered. By default, the processes to be affected are specified by their processIDs. 

Options supported by renice: 

-g Forcewho parameters to be interpreted as process group ID s. 

-u Forcethewho parameters to beinterpreted asusernames. 

-p Reset the who interpretation to be (the default) process ID s 

The following example changes the priority of process ID S987 and 32 and all processes owned by users daemon and root: 

renice +1 987 -u daemon root -p 32 

U sers other than the superuser can only alter the priority of processes they own and can only monotonically increase their 
"nice valued within the range 0 to prio_max ( 20). (This prevents overriding administrative fiats.) The superuser can alter the 
priority of any process and set the priority to any value in the range priojiin (- 20) to prio_max. Useful priorities are: 20 (the 
affected processes run only when nothing else in the system wants to), 0 (the "base" scheduling priority), and anything 
negative (to make things go very fast). 

FILES 

/etc/passwd to map usernames to user IDs 

SEE ALSO 

getpriority(2), setpriority(2) 

BUGS 

N on-superusers cannot increase scheduling priorities of their own processes, even if they were the ones that decreased the 
prioritiesin thefirst place 
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HISTORY 

The renice command appeared in BSD 4.0. 


BSD 4, 9 Junel993 


repquota 

repquota— Summarize quotas for a filesystem. 

SYNOPSIS 

/usr/etc/repquota [ -vug ] filesystem... 

/usr/etc/repquota [ -avug ] 

DESCRIPTION 

repquota prints a summary of thedisk usage and quotas for thespecified filesystems For each user, the current number of 
files and amount of space (in kilobytes) is printed, along with any quotas created with edquota(8). 

OPTIONS 

-a Report on all filesystems indicated in /etc/fstab to be read-write with quotas 

-v Report all quotas even if there is no usage. 

-g Report quotasfor groups. 

-u Report quotasfor users. Thisisthedefault. 

0 nly the superuser can view quotas that are not their own. 

FILES 

quotas Q uota fi le at the filesystem root 

/etc/fstab Default filesystems 

SEE ALSO 

quota(l), quotactl(2), edquota(8), quotacheck(8), quotaon(8) 

8Junel993 


rexecd 

rexecd— Remote execution server. 

SYNOPSIS 

DESCRIPTION 

rexecd is the server for the rexec(3) routine. The server provides remote execution facilities with authentication based on 
usernames and passwords 

rexecd listens for service requests at the port indicated in the exec service specification; see servtces(5). When a service 
request is received, thefollowing protocol is initiated: 

1. Theserverreadscharactersfromthesocketuptoanull \o byte. The resultant string is interpreted asan ASCII number, 



rlognd 


2. If the number received in Step 1 is nonzero, it is interpreted as the port number of a secondary stream to be used for the 
stderr. A second connection is then created to the specified port on the client's machine 

3. A null-terminated usernameof at most 16 characters is retrieved on theinitial socket. 

4. A null-terminated, unencrypted password of at most 16 characters is retrieved on the initial socket. 

5. A null-terminated command to be passed to a shell is retrieved on theinitial socket. The length of the command is 
limited by the upper bound on the size of the system's argument list. 

6 . rexecd then validates the user as is done at login time and, if the authentication was successful, changes to the user's 
home directory and establishes the user and group protectionsof the user. If any of these steps fail, the connection is 
aborted with a diagnostic message returned. 

7. A null byte is returned on theinitial socket and the command line is passed to the normal login shell of the user. The 
shell inherits the network connections established by rexecd. 


DIAGNOSTICS 


Except for the last one listed, all diagnostic messages are returned on theinitial socket, after which any network connections 
are closed. An error is indicated by a leading byte with a value of i (0 is returned in Step 7 upon successful completion of all 
the steps prior to the command execution). 



Login incorrect. 


The name is longer than 16 characters 
The password is longer than 16 characters 

Thecommand line passed exceeds the size of the argument list (as configured into the 
system). 

N 0 password file entry for the username existed or the wrong password was supplied. 
Thechdir command to the home directory failed. 

A fork by the server fai led. 

The user's login shell could not be started. This message is returned on the connection 
associated with the stderr and is not preceded by a flag byte 


SEE ALSO 

rexec(3) 


BUGS 

A facility to allow all data and password exchanges to be encrypted should be present. 

HISTORY 

The rexecd command appeared in BSD 4.2. 

BSD 4.2,16 M arch 1991 


rlogind 

riogind — Remote login server. 

SYNOPSIS 

rlogind [-aln] 

DESCRIPTION 

rlogind is the server for the riogin(l) program. The server provides a remote login facility with authentication based on 
privileged port numbers from trusted hosts. 
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Options supported by riogind; 

-a Ask hostnamefor verification. 

-l Prevent any authentication based on the user's .rhosts file unlessthe user is logging in 

as the superuser. 

-n Disable keep-alive messages. 

riogind listens for service requests at the port indicated in the "login" service specification; see services(5). When a service 
request is received, thefollowing protocol is initiated: 

1. The server checks the client's source port. If the port isnot in the range 512-1023, the server abortsthe connection. 

2. Theserver checks the client's source address and requests the corresponding hostname (see gethostbyaddr(3), hosts(5), 
and named(8)). If the hostname cannot be determined, the dot-notation representation of the host address is used. If the 
hostname isin thesame domain as the server (according to the last two components of the domain name), or if the -a 
option is given, the addresses for the hostname are requested, verifying that the name and address correspond. Normal 
authentication is bypassed if the address verification fails. 

Oncethe source port and address have been checked, riogind proceeds with the authentication process described in rshd(8). 

It then allocates a pseudo terminal (see pty(4)) and manipulates file descriptors so that the slave half of the pseudo terminal 
becomes the stdin, stdout, and stderr for a login process The login process is an instance of the login(l) program, invoked 
with the -f option if authentication has succeeded. If automatic authentication fails the user is prompted to log in as if on a 
standard terminal line 

The parent of the login process manipulates the master side of the pseudo terminal, operating as an intermediary between the 
login process and thj= client instance of the riogin program. In normal operation, the packet protocol described in pty(4) is 
invoked to provide S/Q type facilities and propagate interrupt signals to the remote programs The login process propagates 
the client terminal's baud rate and terminal type, as found in the environment variable term; see environ(7). The screen or 
window size of the terminal is requested from the client, and window size changes from the client arepropagated to the 
pseudo terminal. 

Transport-level keep-alive messages are enabled unlessthe -n option ispresent. The use of keep-alive messages allows sessions 
to be timed out if the client crashes or becomes unreachable 

DIAGNOSTICS 

All initial diagnostic messages are indicated by a leading byte with a value of i, after which any network connections are 
closed. If there are no errors before login isinvoked, a null byte is returned asin indication of success 
Try again . A fork by the server fai led. 

SEE ALSO 

login(l), ruserok(3), rshd(8) 

BUGS 

The authentication procedure used here assumes the integrity of each client machine and the connecting medium. This is 
insecure but isuseful in an "open" environment. 

A facility to allow all data exchanges to be encrypted should be present. 

A more extensible protocol should be used. 

HISTORY 

The riogind command appeared in BSD 4.2. 


BSD 4.2,16 M arch 1991 



route 



route 

route— Show/manipulate the IP routing table. 


SYNOPSIS 



DESCRIPTION 

route manipulates the kernel's IP routing table. Its primary useisto set up static routes to specific hosts or networks via an 
interface after it has been configured with theifconfig(8) program. This version of route is intended solely for use with 
kernel versions 0.99pll4n and newer kernels. 

OPTIONS 

(none) Prints out the kernel routing table, listing destination address, gateway, ndtmask for 

route("Genmask"),flags(u =U p, h =H ost, g =Gateway, d =dynamic, m =M odified), 
Metric (currently not supported), Ret, use, and if ace (which device the route maps to). 

-n Same as previous but shows numerical addresses instead of trying to determine symbolic 

host names 

-v A flag for verbose (not actually used). 

del xxxx Deletes the route associated with the destination addressxxxx. 

add [-net | -host ] xxxx [gw gggg ] Adds a route to the IP address xxxx. The route is a network route if the -net modifier is 

[metric MHMM ] [netmask NNNN] Used Or XXXX isfOUnd in /etc/networks by the getnetbynamef) library function and no 

[dev dddd ] -host modifier is used. 

The gw gggg argument meansthat any IP packets sent to thisaddresswill be routed 
through the specified gateway. Note The specified gateway must be reach able first. This 
usually meansthat you have to set up a static route to the gateway beforehand. 

The metric MHMM modifier is not ydt implemented (and with the -v option will actually 
print a warning). 

The netmask nnnn modifier specifies the ndtmask of the route to be added. This only 
makes sense for a network route and when the address xxxx actually makes sense with 
the specified netmask. If no netmask is given, route guesses it instead, so for most 
normal setups, you won't need to specify a netmask. 

The mss nnnn modifier specifies the TC P mss for the route to be added. This is usually 
used only for fine optimization of routing setups. 

The window nnnn modifier specifies the TC P window for the route to be added. This is 
typically only used on AX.25 networks and with drivers unable to handle back-to-back 
frames- such as the 3c501 or D E600. 

The dev dddd modifier forces the route to be associated with the specified device because 
thekernel will otherwise try to determinethe device on its own (by checking already 
existing routes and device specifications and where the route is added to). In most 
normal networks, you won't need this 

If dev dddd isthe last option on the command line, the word dev may be omitted 
because it's the default. Otherwise the order of the route modifiers (metric, netmask, gw, 
and dev) doesn't matter. 
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EXAMPLES 


route add -net 127.0.0.0 


route add -net 192.56.76.0 
netmask 255.255.255.0 dev eth0 

route add default gw mango-gw 


Adds the normal loopback entry, using netmask 255.0.0.0 (Class A net determined from 
thedestination address) and associated with theio device (assuming this device was 
previously set up correctly with tfconftg(8)). 

Adds a route to the network 192 . 56 . 76 . * via eth0. T he C lass C netmask modifier is not 
really necessary here becausei92.* isaClassC IP address. The word dev can be omitted 
here 

Adds a default route (which will be used if no other route matches). All packets using 
this route will begatewayed through mango-gw. The device that will actually be used for 
that route depends on how you can reach mango-gw; thestatic route to mango-gw will have 
to be set up before 


route add ipx4 si0 route add -net Thiscommand sequence adds the route to the ipx4 host via theSLIP interface 
192.57.66.0 netmask 255.255.255.0 (assuming that ipx4 istheSLIP host) and then adds the net 192.57.66.0 to begatewayed 
gw ipx4 through that host. 


FILES 


/proc/net/route 


/etc/networks 


/etc/hosts 


SEE ALSO 

ifconfig(8) 

HISTORY 

route for Linux wasoriginally written by Fred N. van Kempen (waitjeeuwait.ni.mugnet.org) and then modified by Johannes 
Stilleand LinusTorvaldsfor pll5. Alan Cox added the mss and window optionsfor Linux 1.1.22. 

14Junel994 


routed 

routed- N etwork routing daemon. 

SYNOPSIS 

routed [-d] [-g] j-q] [-s] [-t] [logfile] 

DESCRIPTION 

routed is invoked at boot time to manage the network routing tables. The routing daemon uses a variant of the Xerox N S 
Routing Information Protocol in maintaining up-to-date kernel routing table entries It used a generalized protocol capable 
of use with multiple address types but iscurrently used only for I nternet routing within a cluster of networks 
In normal operation, routed listens on the udp(4) socket for the route(8) service (see services(5)) for routing information 
packets If the host isan internetwork router, it periodically supplies copies of its routing tables to any directly connected 
hosts and networks. 

When routed is started, it uses the siocgifconf iocti(2) to find those directly connected interfaces configured into the system 
and marked "up" (the software loopback interface is ignored). If multiple interfaces are present, it is assumed that the host 
will forward packets between networks, routed then transmitsa request packet on each interface (using a broadcast packet if 
the interface supports it) and enters a loop, listening for request and response packets from other hosts. 




routed 


When a request packet is received, routed formulates a reply based on the information maintained in its internal tables. The 
response packet generated contains a list of known routes, each marked with a "hop count" metric (a count of 16, or greater, 
isconsidered "infinite;'). The metric associated with each route returned provides a metric relative to the sender. 

Response packets received by routed are used to update the routing tables if one of thefollowing conditions issatisfied: 

No routing table entry exists for the destination network or host, and the metric indicates the destination is "reachable" 
(the hop count is not infinite). 

The source host of the packet is the same as the router in the existing routing table entry. That is, updated information is 
being received from the very internetwork router through which packets for the destination are being routed. 

The existing entry in the routing table has not been updated for sometime (defined to be 90 seconds) and the route is at 
least as cost effective as the current route. 

T he new route describes a shorter route to the destination than the one currently stored in the routing tables; the metric 
of the new route is compared against the one stored in the table to decide this 

When an update is applied, routed records the change in its internal tables and updates the kernel routing table. The change 
is reflected i n the next response packet sent. 

In addition to processing incoming packets routed also periodically checks the routing table entries. If an entry has not been 
updated for three minutes the entry's metric is set to infinity and marked for deletion. Deletions are delayed an additional 
60 seconds to ensure the invalidation is propagated throughout the local Internet. 

H osts acting as internetwork routers gratuitously supply their routing tables every 30 seconds to all directly connected hosts 
and networks The response is sent to the broadcast address on nets capable of that function, to the destination address on 
point-to-point links and to the router's own addresson other networks. The normal routing tables are bypassed when 
sending gratuitous responses. The reception of responses on each network is used to determine that the network and 
interface are functioning correctly. If no response is received on an i nterface, another route may be chosen to route around 
the i nterface, or the route may be dropped if no alternative is avai I able. 

Options supported by routed: 

-d Enable additional debugging information to be logged, such as bad packets received. 

-g Thisflagisused on internetwork routers to offer a route to the "default" destination. 

T his is typically used on a gateway to the I nternet or on a gateway that uses another 
routing protocol whose routes are not reported to other local routers. 

-s Supplying thisoption forces routed to supply routing information whether it isacting as 

an internetwork router or not. This is the default if multiple network interfaces are 
present or if a point-to-point link is in use 
-q This is the opposite of the -s option. 

-t If the -t option is specified, all packets sent or received are printed on the standard 

output. In addition, routed will not divorce itself from the controlling terminal so that 
interrupts from the keyboard will kill the process 

Any other argument supplied is interpreted asthenameof filein which routed'sactionsshould be logged. Thislog contains 
information about any changes to the routing tables and, if not tracing all packets a history of recent messages sent and 
recei ved that are related to the changed route. 

In addition to the facilities described previously, routed supports the notion of "distant" passive and active gateways. W hen 
routed is started, it reads the file to find gateways that might not be located using only information from the siOGiFCONFiocti 
(2). Gateways specified in this manner should be marked passive if they are not expected to exchange routing information, 
whereas gateways marked active should be willing to exchange routing information (that is, they should have a routed process 
running on the machine). Routes through passive gateways are installed in the kernel's routing tables once upon startup. 

Such routes are not included in any routing information transmitted. Active gateways are treated equally to network 
interfaces Routing information isdistributed to the gateway, and if no routing information isreceived for a period of the 
time, the associated route is deleted. G ateways marked external are also passive but are not placed in the kernel routing table 
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nor are they included in routing updates. Thefunction of external entries is to inform routed that another routing process 
will install such a route and that alternate routes to that destination should not be installed. Such entries are only required 
when both routers might learn of routes to the same destination. 

The /etc/gateways iscomprised of a series of lines, each in the following format: 

<net|host> namel gateway name2 metric value <passive!active|external> 

T he net or host keyword indicates if the route is to a network or specific host. 

namei is the name of the destination network or host. This can bea symbolic name located in or known to the name server if 
started after named(8) or an Internet address specified in "dot" notation; see inet(3). 
name 2 isthe nameor address of thegateway to which messages should beforwarded. 
value isametricindicatingthehopcounttothedestination host or network. 

One of the keywords passive, active, or external indicates if thegateway should be treated as passive or active (as described 
previously) or whether thegateway is external to the scope of the routed protocol. 

Internetwork routers that are directly attached to the ARPAnet or M ilnet should use the Exterior G ateway Protocol (EG P) to 
gather routing information rather than use a static routing table of passive gateways EGP isrequired in order to provide 
routes for local networks to the rest of the Internet system. Sites needing assistance with such configurations should contact 
the Computer Systems Research Group at Berkeley. 

FILES 

/etc/gateways for distant gateways 

SEE ALSO 

udp(4), icmp(4), XNSrouted(8), htable(8) 

Internet Transport Protocols XSIS 028112, Xerox System Integration Standard 

BUGS 

T he kernel's routing tables may not correspond to those of routed when redirects change or add routes routed should note 
any redirects received by reading the 1C M P packets received via a raw socket. 

routed should incorporate other routing protocols, such asXeroxNS, xNSrouted(8), and EGP . Using separate processesfor 
each requires configuration optionsto avoid redundant or competing routes 

routed should listen to intelligent interfaces such as an IM P, to gather more information. It does not always detect 
unidirectional failuresin network interfaces (such as when the output side fails). 

HISTORY 

The routed command appeared in BSD 4.2. 

BSD 4.2,16 Ward) 1991 


rpc.rusersd 

rpc.rusersd— Logged-in users server. 

SYNOPSIS 

/usr/libexec/rpc.rusersd 

DESCRIPTION 

rpc.rusersd is a server that returns information about users currently logged in to the system. 



rpcinfo 


The currently logged-in users are queried using the rusers(l) command. Therpc.rusersd daemon isusually invoked by 
inetd(8). 

rpc.rusersd USesan RPC protocol defined in /usr/include/rpcsvc. 

SEE ALSO 

rusers(l), who(l), w(l), inetd(8) 

BSD 4.3, 7 Junel993 


rpc.rwalld 

rpc. rwaiid— W rite messages to users currently logged in to the server. 

SYNOPSIS 

/usr/libexec/rpc.rwalld 

DESCRIPTION 

rpc.rwaiid isa server that will send a message to users currently logged in to the system. This server invokes the waii(l) 
command to actually write the messages to the system. 

M essages are sent to this server by therwaii(l) command. The rpc.rwaiid daemon isusually invoked by inetd(8). 
rpc.rwalld USesan RPC protocol defined in /usr/lnclude/rpcsvc/rwall.x. 

SEE ALSO 

rwall(l), wall(l), inetd(8) 

BSD 4.3, 7Junel993 


rpcinfo 

rpcinfo— Report RPC information. 

SYNOPSIS 

rpcinfo -p [host ] 

rpcinfo [-n por t num] -u host program [version] 

rpcinfo [-n port num] -t host program [version] 

rpcinfo -b program version 

DESCRIPTION 

rpcinfo makes an RPC call to an RPC server and reports what it finds 

OPTIONS 

-p Probethe port mapper on host and print a list of all registered RPC programs If host is 

not specified, it defaults to the value returned by hostname(l). 

-u Makean RPC call to procedure 0 of program on the specified host usingUDP and 

report whether a response was received. 

-t Makean RPC call to procedure 0 of program on the specified host usingTCP and report 

whether a response was received. 

-n Use port num as the port number for the -t and -u options instead of the port number 

given by the port mapper. 
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■b M akean RPC broadcast to procedure Oof the specified program and versi on using UD P 

and report all hosts that respond. 

-d D elete registration for the R PC service of the specified program and ver s i on . T his option 

can be exercised only by the superuser. 

The program argument can beeitheranameor a number. If aversion is specified, rpcinfo attempts to call that version of the 
specified program. Otherwise, rpcinfo attempts to find all the registered version numbers for the specified program by calling 
version 0 (which is presumed not to exist; if it does exist, rpcinfo attempts to obtain this information by calling an extremely 
high version number instead) and attempts to call each registered version. N otethat the version number is required for -b 
and -d options 

EXAMPLES 

To show all the RPC services registered on the local machine, use 

rpcinfo -p 

To show all of the RPC services registered on the machine named klaxon, use 

rpcinfo -p klaxon 

To show all machines on the local net that are running the Yellow Pages service use 

rpcinfo -b ypserv ‘version’ ■■ uniq 

’ version' isthe current Yellow Pages version obtained from the results of the -p switch above 
To delete the registration for version 1 of thewaiid service, use 
rpcinfo -d walld 1 

SEE ALSO 

rpc(5), portmap(8), RPC Programming Guide 

BUGS 

In releases prior to SunO S 3.0, the N etwork File System (N FS) did not register itself with the port mapper; rpcinfo cannot 
be used to makeRPC calls to the N FS server on hosts running such releases 

17 December 1987 


rquotad, rpc.rquotad 

rquotad, rpc.rquotad— Remote quota server. 

SYNOPSIS 

/usr/etc/rpc.rquotad 

DESCRIPTION 

rquotad isan rpc(3N ) server that returns quotas for a user of a local filesystem that is mounted by a remote machine over the 
N FS. The results are used by quota(l) to display user quotasfor remote filesystems The rquotad daemon is usually started at 
boot ti me from the rc. net scri pt. 

FILES 

quotas Q uota fi le at the filesystem root 

SEE ALSO 

quota(l), rpc(3N ), nfs(4P), services(5) inetd(8C) 


17 December 1987 
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rshd 

rshd- Remote shell server. 

SYNOPSIS 

rshd [-alnL] 

DESCRIPTION 

The rshd server is the server for the rcmd(3) routine and, consequently, for the rsh(l) program. The server provides remote 
execution facilities with authentication based on privileged port numbers from trusted hosts 
The rshd server listens for service requests at the port indicated in the end service specification; see services(5). W hen a 
service request is received, the following protocol is initiated: 

1. The server checks the client's source port. If the port isnot in the range 512-1023, the server abortsthe connection. 

2. Theserver reads characters from thesocket up to a null (\e) byte. The resultant string is interpreted as an ASCII 
number, base 10. 

3. If the number received in Step 2 is nonzero, it is interpreted astheport number of a secondary stream to be used for the 
stderr. A second connection is then created to the specified port on the client's machine The source port of this second 
connection is also in the range 512-1023. 

4. Theserver checks the client's source address and requests the corresponding hostname (see gethostbyaddr(3), hosts(5), 
and named(8)). If the hostname cannot be determined, the dot-notation representation of the host address is used. If the 
hostname isin thesame domain as the server (according to the last two components of the domain name), or if the -a 
option is given, the addresses for the hostname are requested, verifying that the name and address correspond. If address 
verification fails, the connection is aborted with the message, Host address mismatch. 

5. A null-terminated username of at most 16 characters is retrieved on the initial socket. This username is interpreted as 
the user identity on the client's machine. 

6. A null-terminated username of at most 16 characters is retrieved on the initial socket. This username is interpreted as a 
user identity to use on the server's machine 

7. A null-terminated command to be passed to a shell is retrieved on the initial socket. The length ofthecommand is 
limited by the upper bound on the size of the system's argument list. 

8 . rshd then validates the user using ruserok(3), which uses thefile and thefilefound in the user's home directory. The -l 
option prevents ruserok(3) from doing any validation based on the user's .rhosts file, unlesstheuser is the superuser. 

9. A null byte is returned on the initial socket and the command line is passed to the normal login shell of the user. The 
shell inherits the network connections established by rshd. 

Transport-levd keep-alive messages are enabled unless the-n option ispresent. The use of keep-alive messages allows sessions 
to be timed out if the client crashes or becomes unreachable 

The -l option causes all successful accesses to be logged to sysiogd(8) asauth.into messages and all failed accesses to be 
logged as auth.notice. 


DIAGNOSTICS 


Except for the last one listed, all diagnostic messages are returned on the initial socket, after which any network connections 
are closed. An error is indicated by a leading byte with a value of i (0 is returned in Step 9 upon successful completion of all 
the steps prior to the execution of the login shell). 

Locuser too long. The name of the user on the client's machine is longer than 16 characters. 

Ruser too long. The name of the user on the remote machine is longer than 16 characters, 

command too long. Thecommand linepassed exceedsthesizeoftheargument list (asconfigured into the 

system). 


Login incorrect. N o password file entry for the username existed. 

Remote directory. The chdir command to the home directory failed. 
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Can't fork; try again. 

SEE ALSO 

rsh(l), rcmd(3), ruserok(3) 

BUGS 

The authentication procedure used here assumesthe integrity of each client machine and theconnecting medium. This is 
insecure but isuseful in an "open" environment. 

A facility to allow all data exchanges to be encrypted should be present. 

A more extensible protocol (such asTelnet) should be used. 

BSD 4.2,30 April 1991 


The authentication procedure described previously failed. 

The pipe needed for the stderr wasn't created. 

A fork by the server fai led. 

The user's login shell could not be started. This message is returned on the connection 
associated with the stderr and is not preceded by a flag byte 


rwhod 

rwhod — System status server. 

SYNOPSIS 

DESCRIPTION 

rwhod istheserver that maintainsthe database used bytherwho(l) and ruptime(l) programs. Itsoperation is predicated on 
the ability to broadcast messages on a network. 

rwhod operates as both a producer and consumer of status information. As a producer of information, it periodically queries 
the state of the system and constructs status messages that are broadcast on a network. As a consumer of information, it 
listensfor other rwhod servers' status messages, validating them and then recording them in a collection of files located in the 
directory. 

The server transmits and receives messages at the port indicated in the rwho service specification; see services(5). The 
messages sent and received are of the form: 
struct outmp { 

char out_line[8]; /* tty name */ 
char out_name[8]; /* user id */ 


char wd_type; 
char wd_fill[2]; 

int wd_sendtime; 

int wd_recvtime; 


char wd_hostname[32]; 
int wd_loadav[3]; 

int wd_boottime; 

struct whoent { 

struct outmp we_utmp; 








sendmail 


sizeof (struct whoent)]; 


All fields are converted to network byte order prior to transmission. The load averages are as calculated bythew(l) program 
and represent load averages over the 5-, 10-, and 15-minute intervals prior to a server's transmission; they are multiplied by 
100 for representation in an integer. The hostname included is that returned bythegethostname(2) system call, with any 
trailing domain name omitted. The array at the end of the message contains information about the users logged in to the 
sending machine This information includes the contents of the utmp(5) entry for each non-idle terminal line and avalue 
indicating the time in seconds since a character was last received on the terminal line 

M essages received by the ™ho server are discarded unless they originated at an ™ho server's port. I n addition, if the host's 
name as specified in the message contains any unprintable ASCI I characters, the message is discarded. Valid messages 
received by rwhod are placed in files named in the directory. These files contain only the most recent message in theformat 
described previously. 

Status messages are generated approximately once every three minutes. ™hod performs an niist(3) every 30 minutes to guard 
against the possibility that thisfile is not the system image currently operating. 

SEE ALSO 

rwho(l), ruptime(l) 

BUGS 

There should be a way to relay status information between networks. Status information should be sent only upon request 
rather than continuously. People often interpret the server dying or network communication failures as a machine going 
down. 


HISTORY 

The rwhod command appeared in BSD 4.2. 


BSD 4.2,16 M arch 1991 


sendmail 

sendmail- Send mail over the Internet. 

SYNOPSIS 

sendmail [fI ags ] [address ...] 

newaliases 

mailq [-v] 

smtpd 

DESCRIPTION 

sendmail sends a message to one or more recipients routing the message over whatever networks are necessary, sendmail does 
internetwork forwarding as necessary to deliver the message to the correct place 

sendmail is not intended as a user interface routine. 0 ther programs provide user-friendly front ends, sendmail is used only to 
deliver preformatted messages. 

With no flags, sendmail reads its standard input up to an end-of-file or a line consisting only of a single dot and sends a copy 
of the message found thereto all the addresses listed. It determines the networks to use based on the syntax and contents of 
the addresses 
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Local addresses are looked up in afileand aliased appropriately. Aliasing can be prevented by preceding the address with a 
backslash. Usually, the sender is not included in any alias expansions; for example, if john sends to group and group includes 
john in the expansion, then the let±er will not be delivered to john. 


Flags are 


Go into ARPAN ET mode. All input lines must end with a CR-LF, and all messages will 
be generated with a CR-LF at the end. Also, the From: and Sender: fields are examined 
for the name of the sender. 

Run asa daemon. This requires Berkeley I PC. sendmaii will fork and run in the 
background, listening on socket 25 for incoming SM TP connections This is usually run 
from /etc/rc. 

Initialize the alias database. 

Deliver mail in the usual way (default). 

Print a listing of the queue. 

Use the SMTP protocol as described in RFC 821 on standard input and output. This 
flag implies all the operations of the -ba flag that are compatible with SMTP. 

Read batched SM TP (BSM TP) commands from standard input. 

Run in address test mode This mode reads addresses and shows the steps in parsing; it is 
used for debugging configuration tables 

Verify names only; do not try to collect or deliver a message Verify mode is usually used 
for validating users or mailing lists 
C reate the configuration freeze file 

Use alternate configuration file sendmaii refuses to run as root if an alternate configura¬ 
tion file is specified. Thefrozen configuration file is bypassed, 
set debugging value to x. 

Set the full name of the sender. 

Sdts the name of the "from" person (thesenderof the mail), -f can only be used by 
trusted users (usually root, daemon, and network) or if the person you are trying to 
become is the same as the person you are. 

Set the hop count to n . T he hop count is incremented every time the mai I is processed. 
When it reaches a limit, the mail is returned with an error message the victim of an 
aliasing loop. If not specified, Received: lines in the message are counted. 

Don't do aliasing. 

Set option x to the specified va i ue. Options are described later in this section. 

Processed saved messages in the queue at given intervals If ti me isomitted, process the 
queue once t i me isgiven as a tagged number, with s being seconds, m being minutes h 
being hours, d being days, and w being weeks. For example, -qih30mor -q90m both set the 
time-out to 1 hour, 30 minutes If ti me isspecified, sendmaii runsin background. This 
option can be used safely with -bd. 

Process the queued message with the queue ID i dent. 

P rocess the queued messages that have the stri ng a d d r i n one of the recipient addresses 
Processthequeued messages that have the string ad dr in the sender address 
An alternate and obsoldteform of the -t flag. 

Read message for recipients To:, Cc:, and Bcc: lines are scanned for recipient addresses. 
TheBcc: line is deleted before transmission. Any addresses in the argument list are 
suppressed; that is they do not receive copies even if listed in the message header. 

Go into verbose mode Alias expansions are announced and so on. 
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There are also a number of processing options that can besdt. Usually, these will only be used by a system administrator. 
Options can beset either on the command line using the -o flag or in the configuration file. These are described in detail in 
th e Sendmail Installation and Operation Guide The options are 


A file 


Use alternate alias file 

On mailers that are considered "expensive:' to connect to, don't initiate immediate 
connection. Thisrequiresqueuing. 

Set the delivery mode to *. D eli very modes are i for interactive (synchronous) delivery, 
b for background (asynchronous) delivery, and q for queue only (actual delivery is done 
the next time the queue is run). 

Try to automatically rebuild the alias database if necessary, 
set error processing to mode x . Valid modes are m to mail back the error message w to 
"write" back the error message (or mail it back if the sender is not logged in), p to print 
the errors on the terminal (default), q to throw away error messages (only exit status is 
returned), and etodo special processing for the BerkNet. If the text of the message is 
not mai led back by modes m or w and if the sender is local to this machine, a copy of the 
message is appended to the file in the sender's home directory. 

The mode to use when creating temporary files 
SaveUN IX-styleFrom: linesatthefrontof messages. 

The default group ID to use when calling mailers. 

The SMTP help file 

D o not take dots on a line by themselves as a message terminator. 

Checkpoint the queue file after every n successful deliveries (default isia). Thisavoids 
excessive duplicate deliveries when sending to long mailing lists interrupted by system 
crashes. 


The log level. 

Send also to "mef (the sender) if I am in an alias expansion. 

If set, this message may have old style headers If not set, this message is guaranteed to 
have new style headers (commasinstead of spaces between addresses). If set, an adaptive 
algorithm is used that will correctly determine the header format in most cases. 

Select the directory in which to queue messages 

The time-out on reads if none is set, sendmail will wait forever for a mailer. This option 
violates the word (if not the intent) of the SMTP specification, so thet i meout should 
probably be fairly large. 

Save statistics in the named file 

Always instantiate thequeuefile, even under circumstances where it is not strictly 
necessary. This provides safety against system crashesduring delivery. 

Set the time-out on undelivered messagesin the queue to the specified time. After 
delivery has failed (for example because of a host being down) forthisamount of time 
failed messages will be returned to the sender. The default is three days. 

Sdt the name of the time zone. 

If set, a user database is consulted to get forwarding information. You can consider this 
an adjunct to the aliasing mechanism, except that the database is intended to be 
distributed; aliases are local to a particular host. This might not be available if your 
sendmail does not have the userdb option compiled in. 

Set the default user ID for mailers 

If not set, name server lookups will use a query type of any to find types cname, a, and mx 
and will cause all existing records to be cached by the local server. If there is (or might 
be) a wildcard mx in the local domain or its parents that aresearched, you must set this 
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option, which uses a query type of cname only; otherwise, it causes all fully qualified 
names to match asnamesin the local domain. 


In aliases, the first character of a name can be a vertical bar to cause interpretation of the rest of the name as a command to 
pipe the mail to. It might be necessary to quote the name to keep sendmaii from suppressing the blanks between arguments. 
For example, a common alias is 

msgs: " \ /usr/bin/msgs -s" 

Aliases can also have the syntax to ask sendmaii to read the named file for a list of recipients For example, an alias such as 
poets: include:/usr/local/lib/poets.list" 


would read for the list of addresses making up the group. 

sendmaii returns an exit status describing what it did. The codes are defined in sysexits.h: 


EX_0K 

EX_N0USER 

EXJJNAVAILABLE 

EX_SYNTAX 

EX_S0FTWARE 

EX_0SERR 

EX_N0H0ST 

EX_TEMPFAIL 


Successful completion on all addresses 
U sername not recognized. 

C atchall meaning necessary resources were not available 
Syntax error in address. 

Internal software error, including bad arguments 
Temporary operating system error, such as cannot fork. 
H ostname not recognized. 

M essage could not be sent immediately but was queued. 


If invoked as newaiiases, sendmaii rebuilds the alias database If invoked asmaiiq, sendmaii prints the contents of the mail 
queue If invoked assmtpd, sendmaii forks and runs as a daemon. If invoked asbsmtp, sendmaii processes batched SMTP on 
standard input. If invoked as rung, sendmaii runs through the mail queue and makes what deliveries are possible. 


FILES 

Except for thefile /etc/sendmaii. cf itself, the following pathnames are all specified in /etc/sendmaii. of. T hus, these values 
are only approximations 
/etc/aiiases raw data for alias names 


/etc/aliases.pag 

/etc/aiiases. dir database of alias names 
/etc/sendmaii.cf configuration file 
/etc/sendmaii.fc frozen configuration 
/etc/sendmaii.hf help file 
/var/log/sendmaii.st Collected Statistics 
/var/spool/mqueue/* temp files 


SEE ALSO 

binmaii(l), maii(l), rmaii(l), sysiog(3), aiiases(5), maiiaddr(7), rc(8); D ARPA Internet Request for Comments RFC 819, 
RFC 821, RFC 822; "Sendmaii: An Internetwork M ail Router," SM M and No.16, "Sendmaii Installation and Operation 
Guide," SMM andNo.7. 


HISTORY 

The sendmaii command appeared in BSD 4.2. 


BSD 4,5Auguil991 



sstserial 


setfdprm 

setfdprm— Sets user-provided floppy disk parameters 

SYNOPSIS 

setfdprm [ -p ] device name 

setfdprm [ -p ] device size sectors heads tracks stretch gap rate sped f mt _ g a p 
setfdprm [ -c ] devi ce 
setfdprm [ -y ] devi ce 
setfdprm [ -n ] devi ce 

DESCRIPTION 

setfdprm isa utility that can be used to load disk parameters into the auto-detecting floppy devices to clear old parameter 
sets, and to disable or enable diagnostic messages 

W ithout any options, setfdprm loads the device (usually /dev/fdc or /dev/fdi ) with a new parameter set with the name entry 
found in /etc/fdprm (usually named 360/360 and so on). These parameters stay in effect until the media is changed. 

OPTIONS 

-p device name Permanently loads a new parameter set for the specified auto-configuring floppy device 

for the configuration with name in /etc/fdprm. Alternatively, the parameters can be given 
directly from the command line. 

-c devi ce Clears the parameter set of the specified auto-configuring floppy device. 

-y devi ce Enablesformat detection messages for the specified auto-configuring floppy device. 

-n devi ce D isables format detection messages for the specified auto-configuring floppy device 


BUGS 

This documentation is grossly incomplete 

FILES 

/etc/fdprm 

AUTHOR 

W erner Almesberger (almesberianessie.cs. id. ethz. ch) 


Linux0.99, 20 Nmember 1993 


setserial 

setsertai- Gdt/sdt Linux serial port information. 

SYNOPSIS 

setserial [ -abqvVW ] device [ p a r a me t e r1 [ arg ] ] ... 
setserial -g [ -abv ] devicel ... 

DESCRIPTION 

setserial is a program designed to set or report the configuration information associated with a serial port. This information 
includes what I/O port and IRQ a particular serial port is using, whether the break key should be interpreted asthe Secure 
Attention Key, and so on. 

During the normal bootup process, only COM ports 1-4 are initialized, using the default I/O ports and IRQ values as 
listed. To initialize any additional serial ports or to change the COM 1-4 ports to a nonstandard configuration, the 
setserial program should be used. Typically, it is called from an rc. serial script, which is usually run out of /etc/rc. local. 










Part VIII: A dmi ni strati on and Pri vileged C ommands 


Thedeviceargument or arguments specify the serial device that should be configured or interrogated. It will usually have the 
following form: /dev/cuaie-3]. 

If no parameters are specified, setseriai printsthe port type (such as 8250,16450,16550,16550A), the hardware I/O port, 
the hardware IRQ line, its "baud base," and some of its operational flags 

If the -g option is given, the arguments to setseriai are interpreted as a list of devicesfor which the characteristics of those 
devices should be printed. 

Without the -g option, thefirst argument to setseriai is interpreted as the device to be modified or characteristics to be 
printed, and any additional arguments are interpreted as parameters that should be assigned to that serial device. 

For the most part, superuser privilege is required to set the configuration parameters of a serial port. A few serial port 
parameters can beset by normal users, however, and these are noted as exceptions in thismanual page. 

OPTIONS 

setseriai accepts the following options: 

-a When reporting the configuration of aserial device print all available information. 

-b When reporting the configuration of aserial device print a summary of the device's 

configuration, which might be suitable for printing during the bootup process during 
the/etc/rc script. 

-q Be quiet, setseriai will print fewer lines of output. 

-v Be verbose, setseriai will print additional statusoutput. 

-v Display version and exit. 

-w Do wild interrupt initialization and exit. 


PARAMETERS 


The following parameters can be assigned to aserial port. 

All argument values are assumed to be in decimal unless preceded byex. 




autoconfig 


The port option sets the I/O port as described previously. 

The irq option sets the hardware IRQ as described previously. 

This option is used to set the U ART type. The permitted types are none 8250,16450, 
16550, and 16550A. Because the 8250 and 16450 UARTsdo nothaveFIFOs, and 
because the original 16550 have bugs that maketheFIFOsunusable the FIFO will only 
be used on chips identified asl6550A UARTs. Setting the U ART type to 8250,16450, 
or 16550 will enable the serial port without trying to usethe FIFO. Using theUART 
type none will disable the port. Some internal modems are billed ashavinga"16550A 
UART with a 1KB buffer.” This is a lie. They do not really have a 16550A-compatible 
U ART; instead, what they have is a 16450-compatible UART with a 1KB receive buffer 
to prevent receiver overruns Thisisimportant because they do not have a transmit 
FIFO. Hence, they are not compatible with a 16550A UART, and the autocon¬ 
figuration process will correctly identify them as 16450s If you attempt to override this 
using theuart parameter, you see dropped characters during file transmissions These 
UARTs usually have other problems The skip test parameter also often must be 
specified. 

When this parameter isgiven, setseriai asks the kernel to attempt to automatically 
configure the serial port. The I/O port must be correctly set; the kernel will attempt to 
determine the UART type, and if the auto_irq parameter isset, Linux will attempt to 
automatically determine the IRQ. Theautoconfigure parameter should be given after 
the port, auto_irq, and skip_test parameters have been specified. 







spd_cust 




fourport 
'■fourport 
close_delay delay 


Session_lockout 


A session_lockout 

pgrp_lockout 


A pgrp_lockout 


A hup_notify 


D uring autoconfiguration, try to determine the IRQ. This feature is not guaranteed to 
always produce the correct result; some hardware configurations will fool theLinux 
kernel. 11 is generally safer not to use the auto_trq feature but rather to specify the IRQ 
to be used explicitly, using the trq parameter. 

During autoconfiguration, do not try to determinetheIRQ. 

During autoconfiguration, skip the U ART test. Someinternal modems do not have 
National Semiconductor compatible U ART s but have cheap imitations instead. Some of 
these cheesy imitation UARTsdo not fully support the loopback detection mode, which 
is used by the kernel to make sure there really isaU ART at a particular address before 
attempting to configure it. For certain internal modems, you will need to specify this 
parameter so Linux can initializetheUART correctly. 

D uring autoconfiguration, do not skip the U ART test. 

This option sets the base baud rate which is the clock frequency divided by 16. Usually, 
this value is 115200 , which is also thefastest baud rate which the U ART can support. 

Use 57.6KB when the application requests 38.4KB. Thisparameter can be specified by 
a non-privileged user. 

Use 115KB when the application requests 38.4KB. This parameter can be specified by a 
non-privileged user. 

Use the custom divisor to setthespeed when the application requests 38.4KB. In this 
case the baud rate is the baud_base divided by the divisor. This parameter can be 
specified by a non-privileged user. 

Use 38.4KB when the application requests 38.4KB. Thisparameter can be specified by 
a non-privileged user. 

This option sets the custom divisor. This divisor will be used when thespd_cust option 
is selected and the serial port i s set to 38.4KB by the application.This parameter can be 
specified by a non-privileged user. 

Set the break key at the Secure Attention Key. 

Disable the Secure Attention Key. 

C onfigure the port as an AST Fourport card. 

Disable AST Fourport configuration. 

Specify the amount of time in hundredths of a second, that DTR should remain low on 
a serial line after the callout device is closed before the blocked dial-in device raises D T R 
again. The default value of thisoption isso, or a half-second delay. 

Lock out callout port (/dev/cuaxx) accesses across different sessions. That is, oncea 
process has opened a port, do not allow a processwith a different session ID to open 
that port until the first process has closed it. 

D 0 not lock out callout port accesses across different sessions. 

Lock out callout port (/dev/cuaxx) accesses across different process groups. That is, once 
a process has opened a port, do not allow a process in a different process group to open 
that port until the first process has closed it. 

D 0 not lock out callout port accesses across different process groups. 

N otify a process blocked on opening a dial-in linewhen a processhas finished usinga 
callout line (either by closing it or by the serial line being hung up) by returning eagain 
to the open. 

The application of thisparameter isforgettys that are blocked on a serial port's dial-in 
line T his allows the getty to reset the modem (which may have had its configuration 
modified by the application using the callout device) before blocking on the open again. 
Do not notify a process blocked on opening a dial-in linewhen thecallout device is 
hungup. 
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split_termios 

A split_termios 

callout_nohup 

A callout_nohup 


T reat the termios settings used by the callout device and the termiossdtti ngs used by the 
dial-in devices as separate. 

Usethesametermiosstructureto store both thedial-in and callout ports Thisisthe 
default option. 

If this particular serial port is opened as a callout device, do not hangup the tty when 
carrier detect is dropped. 

Do not skip hanging up the tty when a serial port is opened as a callout device Of 
course, the hupcl termios flag must be enabled if the hangup is to occur. 


CON SID ERATIO N S 0 F CO N FIG U RIN G SERIAL PO RTS 

It is important to note that setsertai merely tells the Linux kernel where it should expect to find the I/O port and IRQ lines 
of a particular serial port. It does not configure the hardware, theactual serial board, to use a particular I/O port. To do that, 
you need to physically program the serial board, usually by setting some jumpers or by switching some DIP switches. 

This section provides some pointers in helping you decide how you wantto configure your serial ports 
The "standard M S-DO S" port associations are 


/dev/ttyso (COM 1), port 0x3f8 IRQ 4 

/dev/ttysi (COM 2), port 0x2f8 IRQ 3 

/dev/ttyS2 (COM 3), port 0x3e8 IRQ 4 

/dev/ttyS3 (COM 4), port 0x2e8 IRQ 3 


D ue to the limitations in the design of the AT/I SA bus architecture, an IRQ line usually cannot be shared between two or 
more serial ports If you attempt to do this, one or both serial ports will become unreliable if you try to use both simulta¬ 
neously. This limitation can be overcome by special multiport serial port boards which are designed to share multiple serial 
portsover a single IRQ line M ultiport serial cards supported by Linux include the AST FourPort, the Accent Async board, 
the Usenet Serial II board, the Bocaboard BB-1004, BB-1008, and BB-2016 boards, and the HUB-6 serial board. 

T he selection of an alternative IRQ line is difficult because most of them are already used. T hefollowing table lists the 
"standard MS-DO S" assignments of available IRQ lines 

IRQ 3 COM2 

IRQ 4 COM 1 

IRQ 5 LPT2 

IRQ 7 LPT1 


M ost people find that IRQ 5 is a good choice assuming that there is only one parallel port active in the computer. Another 

good choice is IRQ 2 (a.k.a. IRQ 9), although this IRQ is sometimes used by network cards and very rarely will VGA cards 

be configured to use IRQ 2 as a vertical retrace interrupt. I f your VGA card is configured this way, try to disable it so you 

can reclaim that IRQ linefor some other card. It's not necessary for Linux and most other operating systems 

The only other available IRQ lines are 3,4, and 7, and these are probably used by the other serial and parallel ports (If your 

serial card has a 16-bit card edge connector and supports higher interrupt numbers then IRQ 10,11,12, and 15 are also 

available.) 

OnAT class machines, IRQ 2isseenaslRQ 9, and Linux will interpret it in this manner. 

IRQsotherthan 2 (9), 3,4, 5,7,10,11,12, and 15 should not be used because they are assigned to other hardware and 
cannot, in general, be changed. Here are the "standard" assignments 

IRQ 0 Timer channel 0 

IRQ 1 Keyboard 

IRQ 2 Cascade for controller 2 

IRQ 3 Serial port 2 

IRQ 4 Serial port 1 





IRQ 5 

Parallel port 2 (Reserved in PS/2) 

IRQ 6 

Floppy diskette 

IRQ 7 

Parallel port 1 

IRQ 8 

Real-time clock 

IRQ 9 

Redirected to IRQ2 

IRQ 10 

Reserved 

IRQ 11 

Reserved 

IRQ 12 

Reserved (Auxiliary device in PS/2) 

IRQ 13 

M ath coprocessor 

IRQ 14 

H ard disk controller 

IRQ 15 

Reserved 


CAUTION 

Using an invalid port can lock up your machine. 

FILES 

/etc/rc.local 
/etc/rc.serial 

SEE ALSO 

tty(4), ttys(4), kernel/chr_drv/serial.c 

AUTHOR 

The original version of setseriai was written by Rick Sladkey (jrs@worid.std.com) and was modified by M ichael K. Johnson 
(j ohnsonm@stolaf.edu). 

This version has since been rewritten from scratch by Theodore Ts'o (tytso@mit.edu) on 1/1/93. Any bugs or problems are 
solely his responsibility. 

sisarial 2.10,27 August 1994 


setsid 

setsid— Run a program in a new session. 

SYNOPSIS 

DESCRIPTION 

setsid runsa program in a new session. 

SEE ALSO 

setsid(2) 

AUTHOR 

Rick Sladkey (jrs@world.std.com) 


Linux 0.99, 20 N member 1993 
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showmount 

showmount — Show mount information for an N FS server. 

SYNOPSIS 

/usr/etc/showmount [\-adehv\][\--all\][\--directories^ 

[\ - -exports\][\ --help\] [\■-version\][\host \] 

DESCRIPTION 

showmount queries the mount daemon on a remote host for information about the state of the N FS server on that machine. 
With no options, showmount lists the set of dientswho are mounting from that host. The output from showmount is designed 
to appear as though it were processed through sort -u. 

OPTIONS 

-a or - -all 
-dor - -directories 
-e Or --exports 
-h Or--help 
-vor - -version 
--no-headers 

SEE ALSO 

rpc.mountd(8), rpc.nfsd(8) 

BUGS 

The completeness and accuracy of the information that showmount displays varies according to the N FS server's implementa¬ 
tion. Because showmount sorts and uniques the output, it is impossible to determine from the output whether a client is 
mounting the same directory more than once 

AUTHOR 

Rick Sladkey (jrs@world.std.com) 

6 October 1993 


List both the client hostname and mounted directory in host :di r format. 
List only the directories mounted by some client. 

Show the N FS server's export list. 

Provide a short help summary. 

Report the current version number of the program. 

Suppress the descri pti ve headi ngs from the output. 


shutdown 

shutdown— Closedown the system. 

SYNOPSIS 

shutdown [ -h 
reboot [ -h | 
fastboot [ -h 
halt [ -h | -r 
fasthalt [ -h 

DESCRIPTION 

In general, shutdown prepares the system for a power down or reboot. An absolute or delta time can be given, and periodic 
messages will be sent to all users warning of the shutdown, 
halt is the same as shutdown -h -q now. 
fasthalt is the same as shutdown -h -q -f now. 


-r ] [ -fqs ] [ now I hh: ss | +mi ns ] 

r ] [ -fqs ] [ now | hh: ss j +mi ns ] 

-r ] [ -fqs ] [ now | hh: ss | +mi ns ] 

] [ -fqs ] [ now | hh: ss | +mi ns ] 

-r ] [ -fqs ] [ now ! hh: ss j +mi ns ] 







g'mpla'nit 


reboot is the same as shutdown -r -q now. 
fastboot is the same as shutdown -r -q -f now. 

The default delta time if none is specified, is two minutes 

Five minutes before shutdown (or immediately, if shutdown is less than five minutes away), the/etc/noiogin file is created 
with a message stating that the system is going down and that logins are no longer permitted. Theiogin(l) program will not 
allow non-superusers to login during this period. A message will be sent to all users at this time 
When the shutdown time arrives, shutdown notifies all users, tells init(8) not to spawn moregetty(8)s, writes the shutdown 
timeinto the /var/iog/wtmp file kills all other processes on the system, sync(2)s, unmounts all the disks, sync(2)s again, waits 
for a second, and then either terminates or reboots the system. 

OPTIONS 


FILES 

/fastboot 
/etc/singleboot 
/etc/nologin 
/var/log/wtmp 

SEE ALSO 

umount(8), login(l), reboot(2), simpleinit(8), init(8) 

BUGS 

Unlike the BSD shutdown, users are notified of shutdown only once or twice, instead of many times, and at shorter and 
shorter intervals as "apocalypse approaches." 

AUTHOR 

poeMaimi.aau.dk. M odified by jrs@world.std.com. 

Linux0.99, 20 N member 1993 


FI alt the system. Do not reboot. This option is used when powering down the system. 
Reboot the system. 

Fast. When the system is rebooted, the filesystems will not be checked. This is arranged 
by creating /fastboot, which /etc/rc must detect (and delete). 

Q uiet. T his uses a default broadcast message and does not prompt the user for one. 
Reboot in single-user mode This is arranged by creating /etc/singieboot, which 
simpieinit(8) detects (and deletes). 


simpleinit 

simpieinit — Process control initialization. 

SYNOPSIS 
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DESCRIPTION 

init is invoked as the last step in the Linux boot sequence If the single option is used, or if thefile /etc/singieboot exists, 
then singleuser mode will be entered, by starting /bin/sh. If thefile /etc/securesingie exists, then the root password will be 
required to start singleuser mode. If the root password does not exist, or if /etc/passwd does not exist, the checking of the 
password will be skipped. 

If thefile /etc/iz exists, then the contents of that file will be read and used to set the tz environment variable for each 
process started by simpieinit. This "feature" isonly available if it's configured at compile time It's not usually needed. 

After singleuser mode isterminated, the /etc/rc file isexecuted, and the information in /etc/inittab will be used to start 
processes 

While init is running, several signals are trapped with special action taken. Because init has PI D 1, sending signals to the 
init process is easy with the kiii(l) command. 

If init catchesasiGHUP (hangup) signal, the /etc/inittab will be read again. If init catches a sigtstp (terminal stop) signal, 
no more processes will be spawned. This is a toggle, which is reset if init catches another sigtstp signal. 

If init catches a sigint (interrupt) signal, init will sync a few times and try to start reboot. Failing this, init will execute the 
system reboot(2) call. Under Linux, it ispossibleto configure theCtrl+Alt+D el sequence to send a signal to init instead of 
rebooting the system. 

THE inittab FILE 

Because of the number of init programs that are appearing in the Linux community, the documentation for the 
/etc/inittab file which is usually found with the inittab(5) man page, is presented here: 

The format is 

ttyline:termcap-entry:getty-command 

An example follows: 

ttyliconsole:/sbin/getty 9600 ttyl 
tty2:console:/sbin/getty 9600 tty2 
tty3:console:/sbin/getty 9600 tty3 
tty4:console:/sbin/getty 9600 tty4 

# tty5:console:/sbin/getty 9600 tty5 

# ttyS1:dumb:/sbin/getty 9600 ttySI 

# ttyS2:dumb:/sbin/getty -m -t60 2400 ttyS2 

Lines beginning with the# character are treated as comments. Please see documentation for thegetty(8) command that you 
are using because there are several ofthesein the Linux community at this time 

FILES 


/etc/singleboot 

/etc/securesingle 

/etc/TZ 

/etc/passwd 

/etc/rc 


SEE ALSO 

inittab(5), ctrlaltdel(8) reboot(8), termcap(5), getty(8), agetty(8), shutdown(8) 






Jiplogn 


BUGS 

This program is called simpieinit to distinguish it from the System V compatible versions of init that are starting to appear 
in the Linux community, simpieinit should be linked to, or made identical with, init for correct functionality. 

AUTHOR 

PeterOrbaek (poeMaimt.aau.dk), version 1.20, with patches for single-user mode by Werner Almesberger. 

Linux0.99, 20 N member 1993 


slattach 

siattach— Attach a network interface to a serial line. 

SYNOPSIS 

slattach [-v] [-p proto] [-s speed] [tty] 


DESCRIPTION 

siattach is a little program that can be used to put a normal terminal ("serial") line into oneof several "network" modes, 
thus allowing you to use it for point-to-point links to other computers 


OPTIONS 

[-v] Enable debugging output. Useful when determining why a given setup doesn't work. 

[ -p pr ot o ] Set a specific kind of protocol to use on the line. The default issdt to csiip, compressed 

SLIP. Other possible values are slip (normal SLIP), ppp (Point-to-Point Protocol), and 
kiss (AX.25TNC protocol). 

[-s speed] Set a specific line speed other than the default. 

If no arguments are given, the current terminal line (usually the login device) is used. 
Otherwise, an attempt is made to claim theindicated terminal port, lock it, and open it. 


FILES 

/dev/cua* 

BUGS 

N one so far. 

AUTHOR 

Fred N . van Kempen (waltjeMwalt.nl.mugnet.org) 


20 September 1993 


sliplogin 

siipiogin- Attach a serial line network interface 

SYNOPSIS 

sliplogin [I o g i n n a me] 

DESCRIPTION 

sliplogin isused to turn the terminal line on standard input into a serial line IP SLIP link to a remote host. To do this, the 
program searches the file for an entry matching i ogi nname (which defaults to the current login name if omitted). If a 
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matching entry isfound, the line isconfigured appropriately for slip (8-bit transparent I/O) and converted to slip line 
discipline Then a shell script is invoked to initialize the slip interface with the appropriate local and remote IP address, 
netmask, and so on. 

The usual initialization script is/etcysiip/siip.igin, but if particular hosts need special initialization, thefile 
/etc/siip/siip.login. loginname will be executed instead if it exists. The script is invoked with the parameters 
The unit number of the slip interface assigned to this line, such asofor sio. 

The speed of the line. 

The arguments from the entry, in order starting with i o g i n n a me. 

Only the superuser can attach a network interface. The interface ^automatically detached when the other end hangs up or 
the siipiogin process dies. If the kernel slip module has been configured for it, all routes through that interface will also 
disappear at the same time. If there is other processing a site wants done upon hangup, thefile /etc/siip/siip. logout or 
/etc/siip/siip. logout, loginname isexecuted if it exists It isgiven the same arguments as the login script. 

FORMATOF/etc/slip. hosts 

Comments (lines starting with a#) and blank lines are ignored. Other lines must start with ai ogi nname, but the remaining 
arguments can be whatever is appropriate for the file that will be executed for that name. Arguments are separated by 
whitespace and follow normal sh(l) quoting conventions (however, i ogi nname cannot be quoted). Usually, lineshavethe 
formiogi nname local- a*fijlfe>s remote-address netmask opt-args. local-address and remote-address are the IP hostnames Or 
addressesof the local and remote endsof theslip line and netmask istheappropriatelP netmask. These arguments are passed 
directly to ifconfig(8). opt-args are optional arguments used to configure the line 

EXAMPLE 

The normal use of siipiogin isto create a entry for each legal, remote slip site with siipiogin astheshell for that entry, 
such as 

Sfoo:ikhuy6:2010:1:slip line to foo:/tmp:/usr/sbin/sliplogin. 

(0 ur convention isto name the account used by remote host hostname as shostname.) Then an entry is added that looks like 




hostname 1 will be evaluated by sh to the local hostname and netmask is the local host IP netmask. 

Note that siipiogin must besetuid to root, and although it's not a security hole moral defectives can use it to place terminal 
lines in an unusable state or deny access to legitimate users of a remote slip line. To prevent this, a site can create a group, say 
slip, that only the slip login accounts are put in and then make sure that /sbin/siipiogin is in group slip and mode 4550 
(setuid root, only group slip can execute binary). 

DIAGNOSTICS 

siipiogin logs various information to the system log daemon, sysiogd(8), with a facility code of daemon. T he messages are 
listed here, grouped by severity level. 

Error Severity 

ioctl (TCGETS): reason 
ioctl (TCSETS): reason 
/etc/slip.hosts: reason 
access denied for user 

Notice Severity 


A tcgets iocti to get the line parameters failed. 

A tcsets iocti to set the line parameters failed. 

The file could not be opened. 

N 0 entry for user wasfound in /etc/siip/siip. hosts 


"attaching slip 


U nit was successfully attached. 



3/nc 


SEE ALSO 

slattach(8), syslogd(8) 

HISTORY 

The siipiogin command iscurrently in beta test. 

5 August 1991 


swapon, swapoff 

swapon, swapoff— Enable/disable devices and filesfor paging and swapping. 

SYNOPSIS 

/sbin/swapon special f i I e ... 

/sbin/swapoff -a 
/sbin/swapoff specia Ifi I e ... 

DESCRIPTION 

swapon isused to specify devices on which paging and swapping are to take place Calls to swapon usually occur in the system 
multiuser initialization file /etc/rc making all avap devices available, so that the paging and swapping activity is interleaved 
across several devicesand files. 

Usually, thefirstform isused: 

-a All devices marked assw swap devices in /etc/fstab are made available, 

swapoff disables swapping on the specified devices and files or on all swap entries in /etc/fstab when the -a flag is given. 

SEE ALSO 

swapon(2), swapoff(2), fstab(5), init(8), mkswap(8), rc(8), mount(8) 

FILES 

/dev/hd[ab] ? Standard paging devices 

/dev/sd[ab] ? Standard (SCSI) pagingdevices 

/etc/fstab ASCII filesystem description table 

HISTORY 

The swapon command appeared in 4.0 BSD. 

AUTHORS 

Seethe Linux mount(8) man page for a complete author list. Primary contributors include Doug Quale, H .J. Lu, Rick 
Sladkey, and Stephen Tweedie. 

Linux 0.99, 27 N member 1993 


sync 

sync— Flush Linux filesystem buffers. 

SYNOPSIS 
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DESCRIPTION 

sync executes sync(2), which flushes the filesystem buffers to disk, sync should be called before the processor is halted in an 
unusual manner (before causing a kernel panic when debugging new kernel code). In general, the processor should be halted 
using the reboot(8) or hait(8) commands, which attempt to putthesystem in a quiescent state before calling sync(2). 

From Linus: "N otethat sync isonly guaranteed to schedule the dirty blocks for writing: It can actually take a short time 
before all the blocks are finally written. If you are doing the sync with the expectation of killing the machine soon after, 
please take this into account and sleep for a few seconds (Thereboot(8) command takes these precautions)" 

SEE ALSO 

sync(2), update(8), reboot(8), halt(8) 

AUTHOR 

LinUST Orvalds( torvalds@cs.helsinki.fi) 

Linux 0.99, 20 N member 1993 


sysklogd 

syskiogd— Linux system logging utilities 

DESCRIPTION 

syskiogd provides two system utilities, which provide support for system logging and kernel message trapping. Support of 
both inetd and U NIX domain sockets enables this utility package to support both local and remote logging. 

System logging is provided by a version of sysiogd derived from the stock BSD sources. Support for kernel logging is 
provided bythekiogd utility, which allowskernel logging to be conducted in either a stand-alone fashion orasadient of 
sysiogd. 

Although the sysiogd sources have been heavily modified, a couple of notes are in order. First of all, there has been a 
systematic attempt to ensure that sysiogd follows standard BSD behavior as its default. The second important concept to 
note isthat this version of sysiogd interacts transparently with the version of sysiog found in the standard libraries. If a 
binary linked to the standard shared libraries fails to function correctly, we want an example of the anomalous behavior. 

CONFIGURATION FILE SYNTAX DIFFERENCES 

sysiogd uses a slightly different syntax for its configuration file from that of the original BSD sources. 0 ri gin ally, all messages 
of a specific priority and above were forwarded to the log file. 

For example, the following line caused all output from the daemon facilities to go into /usr/adm/daemons: 

# Sample sysiog.conf 
daemon.debug /usr/adm/daemons 

Under the new scheme, this behavior remainsthesame. The difference isthe addition of two new wildcard specifiers: 
the asterisk (*) and theequalssign (=). The * specifies that all messagesfor the indicated facility are to be directed to the 
destination. N otethat this behavior is degenerate with specifying a priority level of debug. Users have indicated that the 
asterisk notation is more intuitive. 

The= wildcard is used to restrict logging to the specified priority class. This allows, for example, routing only debug messages 
to a particular logging source 

For example, thefollowing line in sysiog. conf directs debug messages from all sources to the /usr/adm/debug file: 

# Sample sysiog.conf 
daemon.=debug /usr/adm/debug 
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This may take some acclimatization for those individuals used to the pure BSD behavior, but testers have indicated that this 
syntax issomewhat more flexible than the BSD behavior. Note that these changes should not affect standard sysiog.conf 
files You must specifically modify the configuration files to obtain the enhanced behavior. 

SUPPORT FOR REMOTE LOGGING 

These modifications provide network support to thesysiogd facility. N etwork support means that messages can be forwarded 
from one node running sysiogd to another node running sysiogd where they will be actually logged to a disk file. 

The strategy is to have sysiogd listen on aU NIX domain socket for locally generated log messages This behavior will allow 
sysiogd to interoperate with thesysiog found in the standard C library. Atthe same time sysiogd listens on the standard 
sysiog port for messages forwarded from other hosts. T o have this work correctly, the services files (typically found in 
/usr/etc/inet) must have the following entry: 
sysiog 514/udp 

To cause messages to be forwarded to another host, replace the normal file line in the sysiog.conf file with the name of the 
host to which the messages is to be sent prepended with an e. 

For example, to forward all messages to a remote host, use the following sysiog.conf entry: 

# Sample sysiogd configuration file to 

# messages to a remote host forward all. 

.* ghostname 

To forward all kernel messages to a remote host, the configuration file is 

# Sample configuration file to forward all kernel 

# messages to a remote host, 
kern.* ghostname 

OUTPUT TO NAMED PIPES (FIFOS) 

This version of sysiogd has support for logging output to named pipes(FIFOs). A FIFO or named pipe can be used asa 
destination for log messages by prepending a | to the name of the file This is handy for debugging. N ote that the FI FO must 
be created with themkfifo command before sysiogd is started. 

The following configuration file routes debug messages from the kernel to a FI FO: 

# Sample configuration to route kernel debugging 

# messages ONLY to /usr/adm/debug which is a 

# named pipe. 

kern.=debug ]/usr/adm/debug 

INSTALLATION CONCERNS 

There is probably one important consideration when installing this version of sysiogd. This version of sysiogd is dependent 
on proper formatting of messages by thesysiog function. T he functioning of thesysiog function in the shared libraries 
changed somewhere in the region of iibc.so.4.[2-4].n. The specific change was to null-terminatethe message before 
transmitting it to the /dev/iog socket. Proper functioning of this version of sysiogd is dependent on null-termination of the 
message. 

This problem will typically manifest itself if old statically linked binaries are being used on the system. Binaries using old 
versions of the sysiog function will cause empty lines to belogged, followed by the message with thefirst character in the 
message removed. Relinking these binaries to newer versions of the shared libraries will correct this problem. 

SECURITY THREATS 

There isthe potential for thesysiogd daemon to be used as a conduit for a denial of service attack. Thanks go to John 
Morrison (jmorriso@rfiab.ee. ubc.ca) for alerting me to this potential. A rogue programmer could very easily flood the 
sysiogd daemon with sysiog messages resulting in the log files consuming all the remaining space on the filesystem. 
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Activating logging over the inet domain sockets will of course expose a system to risks outside of programs or individuals on 
the local machine. 

Version 1.2 of the utility set will address this problem. In the meantime, there are a number of methods for protecting a 
machine: 

1. Logging can bedirected to an isolated or non-root filesystem, which, if filled, will not impairthe machine 

2. The ext2 filesystem can be used, which can be configured to limit a certain percentage of a filesystem to usage by root 
only. Note that this will require sysiogd to be run as a non-root process. Also note that this will prevent usage of remote 
logging because sysiogd will be unable to bind to the 514/U D P socket. 

3. Disabling inet domain sockets will limit risk to thelocal machine. 

4. U se Step 3 and if the problem persists and is not secondary to a rogue program or daemon, get a 3.5 foot (approximately 
1 meter) length of sucker rod and have a chat with the user in question. A sucker rod is3/4-, 7/8-, or 1-inch hardened 
steel rod, male threaded on each end. Itsprimary use in theoil industry in Western North Dakota and other locations is 
to pump-suck oil from oil wells Secondary uses are for the construction of cattle feed lots and for dealing with the 
occasional recalcitrant or belligerent individual. 

FILES 

/etc/syslog.conf 

BUGS 

Primarily, security concerns will be addressed in version 1.2. 

SEE ALSO 

klogd(l) 

COLLABORATORS 

D r. G reg W ettstein (greg%wind.uucp@plains.nodak.edu) 

Enjellic Systems D evelopment 

Oncology Research Division Computing Facility 

Roger M aris C ancer C enter 

Fargo, N D 

Stephen T weedie 

D epartment of Computer Science 

Edinburgh University, Scotland 

JuhaVirtanen 

(jiivee@hut.fi) 

ShaneAlderton 

(shane@scs.apana.org.au) 

Verson 1.1, 28 January 1994 


sysiogd 

sysiogd — Log systems messages. 

SYNOPSIS 

sysiogd [-f config.file] [-m mark.! nterval ] [-p log.socket] 

DESCRIPTION 

sysiogd reads and logs messages to the system console, log files, and other machines or users as specified by its configuration 
file. The options are as follows: 
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-f Specify the pathname of an alternate configuration file; the default is /etc/sysiog.cont. 

-m Select the number of minutes between "mark" messages; the default is 20 minutes. 

-p Specify the pathname of an alternate log socket; the default is /dev/iog. 

sysiogd reads its configuration file when it starts up and whenever it receives a hangup signal. For information on theformat 

of the configuration file see sysiog.conf(5). 

sysiogd reads messages from the U N IX domain socket /dev/iog, from an Internet domain socket specified in /etc/services, 
and from the special device /dev/kiog (to read kernel messages). 

sysiogd createsthefile /var/run/sysiog.pid and stores its process ID there. Thiscan be used to kill or reconfigure sysiogd. 

T he message sent to sysiogd should consist of a single line. T he message can contain a priority code, which should be a 
preceding decimal number in angle braces, such as<5>. This priority code should map into the priorities defined in the 
include file <sys/syslog.h>. 


FILES 

/etc/syslog.conf 

/var/run/syslog.pid 

/dev/log 

/dev/klog 


The configuration file 

The process ID of current sysiogd 

Name of the U N IX domain datagram log socket 

The kernel log device 


SEE ALSO 

logger(l), syslog(3), services(5), syslog.conf(5) 

HISTORY 

The sysiogd command appeared in BSD 4.3. 

BSD 4.2,16 M arch 1991 
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taikd- Remote user communication server. 

SYNOPSIS 


DESCRIPTION 

taikd isthe server that notifies a user that someone else wants to initiate a conversation. It acts a repository of invitations, 
responding to requests by clients who want to rendezvous to hold a conversation. In normal operation, a client, thecaller, 
initiatesa rendezvous by sending a ctl msg to the server of type look up (see protocois/taikd.h). This causes theserver to 
search its invitation tables to check if an invitation currently exists for the caller (to speak to the callee specified in the 
message). If the lookup fails, the caller then sends an announce message, causing the server to broadcast an announcement on 
the callee's login ports requesting contact. W hen the callee responds, the local server uses the recorded invitation to respond 
with the appropriate rendezvous address and thecaller and callee client programs establish a stream connection through 
which the conversation takes place 

SEE ALSO 

talk(l), write(l) 
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HISTORY 

Thetaikd command appeared in BSD 4.3. 


BSD 4.3,16 M arch 1991 
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teinetd— DARPA Telnet protocol server. 

SYNOPSIS 

/etc/telnetd [-debug [port]] [ -1] [ -D opt i ons ][ -D r eport ] 

DESCRIPTION 

teinetd is a server that supports the DAR PA standard Telnet virtual terminal protocol, teinetd is invoked by the I nternet 
server (see inetd(8)), usually for requests to connect to theTelnet port as indicated by the /etc/services file (see 
services(5)). If desired the -debug can be used, to start up teinetd manually, instead of through tnetd(8). If started up this 
way, port may be specified to run teinetd on an alternateTCP port number. 

The -d option can be used for debugging purposes. ThisallowsTelnetto print debugging information to the connection, 
allowing the user to see what teinetd is doing. There are several modifiers: opt i ons prints information about the negotiation 
of Telnet options, report prints the options information, plus some additional information about what processing isgoing 
on, net dot a displays the data stream received by teinetd, ptydata displaysdata written tothepty.and exercise has not been 
implemented yet. 

teinetd operates by allocating a pseudo-terminal device (seepty(4)) for a client) and then creating a login process that has the 
slave side of the pseudo-terminal asstdin, stdout.and stdem. teinetd manipulates the master side of the pseudo-terminal, 
implementing theTelnet protocol and passing characters between the remote client and thelogin process. 

W hen a Telnet session isstarted, teinetd sendsT elnet optionsto the client side, indicating a willingness to do a remote echo 
of characters, to suppress go ahead, to do remote flow control, and to receive terminal type information, terminal Speed 
information, and window size information from the remote client. If the remote client is willing, the remote terminal type is 
propagated in the environment of the created login process. Thepseudo-terminal allocated to the client is configured to 
operate in cooked mode and with xtabs and crmod enabled (see tty(4)). 

teinetd is willing to do echo, binary, suppress go ahead, and timing mark, teinetd is willing to have the remote client 
do linemode, binary, terminal type, terminal speed, window size, toggle flow control, environment, X display location, and 
suppress go ahead. 

If the file /etc/issue, net is present, teinetd will show its contents before the login prompt of a Telnet session (see 
issue.net(5)). 

SEE ALSO 

telnet(l), issue.net(5) 

BUGS 

SomeTelnet commands are only partially implemented. 

Because of bugs in theoriginal 4.2 BSD teinet(l), teinetd performs some dubious protocol exchanges to try to discover if 
the remote client is, in fact, a 4.2 BSD teinet(l). 

Binary mode has no common interpretation except between similar operating systems (UN IX, in this case). 
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The terminal type name received from the remote client is converted to lowercase teinetd never sendsT elnet go ahead 
commands 

20 April 1991 
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tftpd— D ARPA Trivial FileTransfer Protocol server. 

SYNOPSIS 

tftpd [di rectory ...] 

DESCRIPTION 

tftpd isa server that supports the D ARPA T rivial FileT ransfer Protocol. TheT FTP server operates at the port indicated in 
the tftp service description; see servtces(5). The server is usually started by tnetd(8). 

The use of tftp(l) does not require an account or password on the remote system. Due to the lack of authentication 
information, tftpd will allow only publicly readablefiles to be accessed. Files may be written only if they already exist and are 
publicly writable Note that this extends the concept of public to include all userson all hosts that can be reached through 
the network; this may not be appropriate on all systems, and its implications should be considered before enabling the tftp 
service. The server should have the user ID with the lowest possible privilege. 

SEE ALSO 

tftp(l), inetd(8) 

HISTORY 

The tftpd command appeared in BSD 4.2. 

BSD 4.2,13 May 1991 


timed 

timed— T i me server daemon. 

SYNOPSIS 

timed [ -M] [ t] [-d] [-i network] [-n network] [-F host 1 host2 ...] 

DESCRIPTION 

timed isa time server daemon and is usually invoked atboottimefrom the rc(8) file. It synchronizes thehost'sti me with the 
time of other machines in a local area network running timed(8). These time servers will slow down the clocks of some 
machines and speed up the clocks of others to bring them to the average network time. The average network time is 
computed from measurements of clock differences using the 1C M P timestamp request message. 

The service provided by timed is based on a master-slave scheme When timed(8) is started on a machine it asks the master 
for the network time and sets the host'sdock to that time After that, it accepts synchronization messages periodically sent by 
the master and calls ad jtime(2) to perform the needed correctionson the host's clock. 

It also communicates with date(l) to set the date globally and with timedc(8), a timed control program. If the machine 
running the master crashes, then the slaves elect anew master from among slaves running with the -m flag. A timed running 
without the -m or -f flags remains a slave T he -1 flag enables timed to trace the messages it receives in the file 
/var/iog/timed. log. Tracing can be turned on or off by the program timedc(8). The -d flag isfor debugging the daemon. 

It causes the program to not put itself into the background. Usually, timed checks for a master time server on each network 
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to which it isconnected, except as modified by the options It requests synchronization service from thefirst master server 
located. If permitted by the -m flag, it provides synchronization service on any attached networks on which no current master 
server is detected. Such a server propagates the time computed by the top-level master. The -n flag, followed by the name of 
a network that the host isconnected to (see networks(5)), overrides the default choice of the network addresses made by the 
program. Each time the -n flag appears that network name is added to a list of valid networks. All other networks are 
ignored. The -i flag, followed by the name of a network to which the host is connected (see networks(5)), overrides the 
default choice of the network addresses made by the program. Each time the -i flag appears that network name is added to a 
list of networks to ignore. All other networks are used bythetimedaemon.The-nand -i flags are meaninglessif used 
together. 

timed checksfor a master timeserver on each network to which it isconnected, except asmodified by the -n and -i options 
If it finds masters on more than one network, it chooses one network on which to be a "slave" and then periodically checks 
the other networks to see if the masters there have disappeared. 

0 ne way to synchronize a group of machines is to use an N T P daemon to synchronize the clock of one machine to a distant 
standard or a radio receiver and -F hostname to tell itstimed daemon to trust only itself. 

Messages printed by the kernel on the system console occur with interrupts disabled. Thismeansthat the clock stops while 
they are printing. A machine with many disk or network hardware problems and consequent messages cannot keep good 
time by itself. Each message typically causes the clock to lose a dozen milliseconds. A time daemon can correct the result. 

M essages in the system log about machines that failed to respond usually indicate machines that crashed or were turned off. 
Complaints about machines that failed to respond to initial time settings are often associated with "multi-homed" machines 
that looked for time masters on more than one network and eventually chose to become a slave on the other network. 

WARNING 

If two or more time daemons, whether timed, NTP, try to adjust the same clock, temporal chaos will result. If both this and 
another time daemon are run on the same machine, ensure that the -f flag is used, so that timed never attempts to adjust the 
local clock. 

The protocol is based on UD P/IP broadcasts. All machines within the range of a broadcast that are using the TSP protocol 
must cooperate. There cannot be more than a single administrative domain using the -f flag among all machines reached by 
a broadcast packet. Failure to follow this rule is usually indicated by complaints concerning "untrusted" machines in the 
system log. 

FILES 

/var/iog/timed. log tracing file for timed 
/var/iog/timed.masteriog log file for master timed 

SEE ALSO 

date(l), adjtime(2), gettimeofday(2), icmp(4), timedc(8), "TSP: TheTime Synchronization Protocol for UN IX 4.3 BSD," 

R. Gusella, S.Zatti. 

HISTORY 

The timed daemon appeared in BSD 4.3. 

BSD 4.3,11 May 1993 
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timedc— Timed control program. 

SYNOPSIS 

timedc [command] [argument ...] 
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DESCRIPTION 

timedc is used to control the operation of thetimed(8) program. It may be used to 
Measure the differences between machines'clocks 
Find the location where the master time server isrunning 
Enable or disable tracing of messages received by timed 
Perform various debugging actions 

Without any arguments, timedc will prompt for commands from the standard input. If argumentsare supplied, timedc 
interprets the first argument as a command and the remaining arguments as parameters to the command. The standard input 
may be redirected, causing timedc to read commands from afile Commands may be abbreviated; recognized commands are 

help [command ...] 

clockdiff host ... 

msite [host ...] 
trace {on | off} 
election host 

quit Exit from timedc 

Other commands may be included for use in testing and debugging timed; the help command and the program source may 
be consulted for details. 

FILES 

/var/iog/timed. log tracing file for timed 
/var/iog/timed.masteriog log file for master timed 

SEE ALSO 

date(l), adjtime(2), icmp(4), timed(8), "TSP: TheTime Synchronization Protocol for UNI IX 4.3 BSD," R. Gusella, S. Zatti. 

DIAGNOSTICS 

?Ambiguous command Abbreviation matches more than one command 

?Invalid command N 0 match found 

?priviieged command C ommand can be executed by root only 


Print a short description of each command specified in the argument list or, if no 
arguments are given, a list of the recognized commands. 

C ompute the differences between the clock of the host machine and the clocks of the 

machines given as arguments 

Show the master time server for specified hosts 

Enableor disable the tracing of incoming messages to timed in thefile 

Asks the daemon on the target host to reset its "election" timers and to ensure that a 

time master has been elected. 


HISTORY 

The timedc command appeared in BSD 4.3. 
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traceroute— Print the route that packets take to the network host. 

SYNOPSIS 

traceroute [-m max_111 ] [-n] [-p port] [ -q nquer i es ] 

[ -r ] [-s src_addr] [ -t t os] [ -w wai 11 i me] host [packet si ze] 
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DESCRIPTION 

T he I nternet is a large and complex aggregation of network hardware, connected together by gateways. T racking the route 
one's packets follow (or finding the miscreant gateway that's discarding your packets) can be difficult, traceroute utilizes the 
IP protocol time-to-live field and attempts to elicit an icmp time_exceeded response from each gateway along the path to 
some host. 

Theonly mandatory parameter is the destination hostnameor IP number. The default probe datagram length is 38 bytes, 
but this can be increased by specifying a packet size (in bytes) after the destination hostname. 

Other options are 

Set the max time-to-live (max number of hops) used in outgoing probe packets. The 
default is 30 hops (the same default used for TCP connections). 

Print hop addresses numerically rather than symbolically and numerically (saves a 
nameserver address-to-name lookup for each gateway found on the path). 

Set the base U D P port number used in probes (default is33434). traceroute hopes that 
nothing is listening on UDP ports base to base+nhops-latthedestination hostfsoan 
icmp portjjnreachable message will be returned to terminate the route tracing). If 
something is listening on a port in the default range, this option can be used to pick an 
unused port range 

Sdt the number of probes per tti to nquer i es (default is three probes). 

Bypass the normal routing tables and send directly to a host on an attached network. If 
the host is not on a directly attached network, an error is returned. This option can be 
used to ping a local host through an interface that has no route through it (for example 
after the interface was dropped by routed(8)). 

Use the following IP address (which must be given as an IP number, not a hostname) as 
the source address in outgoing probe packets. 0 n hosts with more than one IP address, 
thisoption can be used to force the source address to be something other than the IP 
address of the interface the probe packet is sent on. If the IP address is not one of this 
machine's interface addresses, an error is returned and nothing issent. 

Set thetype-of-service in probe packets to the following value (default zero). The value 
must beadecimal integer in therangeoto 255 . Thisoption can be used to see if 
different types of service result in different paths. (If you are not running a BSD 4.3 
tahoeor later system, this may be academic because the normal network services such as 
Telnet and FTP don’t let you control theTOS). Not all values of TO S are legal or 
meaningful; seethelP spec for definitions Useful values are probably (low delay) and 
(high throughput). 

Verbose output. Received ICM P packets other than time_exceeded and uNREACHABLEsare 
listed. 

Sdt the time (in seconds) to wait for a response to a probe (default is 3 seconds). 

This program attempts to trace the route an IP packet would follow to some Internet host by launching UDP probe packets 
with a small tti (time to live) and then listening for an ICM P "time exceeded" reply from agateway. We start our probes 
with atti of one and increase by one until we get an ICM P "port unreachable" (which means we got to "host") or hit a max 
(which defaults to 30 hops and can be changed with the -m flag). Three probes (changed with the -q flag) are sent at each tti 
setting and a line is printed showing the tti, address of the gateway, and round-trip time of each probe. If the probe answers 
come from different gateways the address of each responding system will be printed. If there is no response within a three 
second time-out interval (changed with the -w flag), a * is printed for that probe. 

We don't want the destination host to process theU DP probe packets so the destination port is set to an unlikely value (if 
some clod on the destination is using that value it can be changed with the -p flag). 
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A sample use and output might be 

[yak 71]% traceroute nis.nsf.net. 



N ote that L ines 2 and 3 are the same. T his is due to a buggy kernel on the second hop system- ibi ■ csam. arpa— that 
forwards packets with a zero tti (a bug in the distributed version of 4.3 BSD). Note that you have to guess what path the 
packets are taking cross-country because the N SFN et (129.140) doesn't supply address-to-nametranslationsfor its N SSs 
A more interesting example is 

[yak 72]% traceroute allspice.lcs.mit.edu. 

traceroute to allspice.lcs.mit.edu (18.26.0.115), 30 hops max 

1 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms 

2 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 19 ms 19 ms 

3 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 19 ms 

4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 19 ms 39 ms 39 ms 

5 ccn-nerif22.Berkeley.EDU (128.32.168.22) 20 ms 39 ms 39 ms 



10 129.140.81.7(129.140.81.7) 199ms 180ms 300ms 

11 129.140.72.17 (129.140.72.17) 300 ms 239 ms 239 ms 



18 ALLSPICE.LCS.MIT.EDU (18.26.0.115) 339 ms 279 ms 279 ms 

Note that the gateways 12,14,15,16, and 17 hop away. Either don't send ICM P "time exceeded" messages or send them 
with atti too small to reach us Lines 14-17 are running the M IT C Gateway code that doesn't send "timeexceeded"s God 
only knows what's going on with 12. 

The si lent gateway 12 may be the result of a bug in the 4.[23] BSD network code (and its derivatives): 4.x (x<=3) sends an 
unreachable message using whatever tti remains in the original datagram. Because for gateways the remaining tti is zero, the 
ICM P "time exceeded" is guaranteed to not make it back to us. The behavior of this bug is slightly more interesting when it 
appears on thedestination system: 

helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms 

lilac-dmc.Berkeley.EDU (128.32.216.1) 39ms 19ms 39ms 
lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 39 ms 19 ms 

ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 19 ms 

ccn-nerif35.Berkeley.EDU (128.32.168.35) 39ms 39ms 39ms 
csgw.Berkeley.EDU (128.32.133.254) 39 ms 59 ms 39 ms 
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12 * * * 

13 rip.Berkeley.EDU (128.32.131.22) 59ms! 39ms! 39ms 

Notice that there are 12 "gateways" (13 isthefinal destination) and exactly the last half of them are "missing.” What's really 
happening is that rip (a Sun-3 running Sun OS3.5) is using them from our arriving datagram as them in its 1C M P reply. 
The reply will time out on the return path (with no notice sent to anyone because 1C M Ps aren't sent for ICM Ps) until we 
probe with a tti that's at least twice the path length. That is, rip is really only seven hops away. A reply that returns with a 
tti of i is a clue this problem exists, traceroute prints a ! after the time if them is less than or equal to 1. Because vendors 
ship a lot of obsolete (D EC U Itrix, Sun 3.x) or non-standard H PU X software, expect to see this problem frequently or take 
care picking the target host of your probes Other possible annotations after thetime are ih, in, ip (got a host, network, or 
protocol unreachable), is, or if (source routefai led or fragmentation needed- neither of these should ever occur and the 
associated gateway is busted if you see one). If almost all the probes result in some kind of unreachable, traceroute will give 
up and exit. 

This program is intended forusein network testing, measurement, and management. It should be used primarily for manual 
fault isolation. Because of the load it could impose on the network, it is unwise to use traceroute during normal operations 
or from automated scripts 

AUTHOR 

Implemented by V an J acobson from a suggestion by Steve Deering. Debugged by a cast of thousands with particularly 
cogent suggestions or fixes from C. Philip Wood, Tim Seaver, and Ken Adelman. 

SEE ALSO 

netstat(l), ping(8) 

BSD 4.3, 6 Junel993 
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tune 2 ts— Adjust tunable filesystem parameters on second extended filesystems. 

SYNOPSIS 

tune2fs [ -1 ][-c max-mount-counts ][-e errdrs-behavior ] 

[-i interval-between-checks ][ -m reserved-blocks-percentage ] 

[-r reserved-bl oc ks-count ][ -u user ][ -g group Jdevice 

DESCRIPTION 

tune 2 ts adjusts tunable filesystem parameterson a Linux second extended filesystem. 

N ever use tune 2 fs on a read/write mounted filesystem to change parameters! 

OPTIONS 

-c max-mount-counts Adjust the maximal mounts count between two filesystem checks 

-e errors-behavi or Changethe behavior of thekernel codewhen errors are detected, er r or s-behav or can 

be one of the following: 
continue Continue normal execution, 

remount-ro Remount the filesystem read-only, 

panic C auses a kernel panic. 
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■g group Sdt the user group that can benefit from the reserved blocks group can be a numerical 

GID or a group name 

-i i nt er vai - bet ween-checks [d>|w] Adjust the maximal time between two filesystem checks No postfix ora results in days, 
nr in months, and w in weeks A value of 0 will disable thetime-dependent checking. 

-1 List the contents of thefilesystem superblock. 

-m reserved - bi ocks - percentage Adjust the reserved blocks percentage on the given device. 

-r reserved-bi ocks-count Adjust the reserved blocks count on the given device 

-u user Set the user who can benefit from the reserved blocks, user can bea numerical U ID ora 

username 


BUGS 

W e didn't find any bugs. Perhaps there are bugs, but it's unlikely. 

WARNING 

U sethis utility at your own risk. You're modifying filesystems 

AUTHOR 

tune2fs was written by Remy Card (card@masi.ibp.fr), the developer and maintainer of the ext2 filesystem. tune2fs 
uses the ext2fs library written byTheodoreT'so (tytso@mit.edu). This manual page was written by Christian Kuhtz 
(chk@data-hh.Hanse.DE). Time-dependent checking was added by U we Ohse (uwe@tirka.gun.de). 

AVAILABILITY 

tune2fs is available for anonymous FTP from ftp.ibp.fr and tsx-11.mit.edu in /pub/linux/packages/ext2fs. 

SEE ALSO 

dumpe2fs(8), e2fsck(8), mke2fs(8) 

Vera on 0.5b, N ovember 1994 


tunelp 

tuneip— set various parameters for the Ip device. 

SYNOPSIS 

tunelp devi ce (-iJ M) | -t Tl HE j -c CHARS 
i -wWAIT ; -a [on|off] | -o [onjoff] | -C [on[off] 

I -r i -s | -q [onjoff] ] 

DESCRIPTION 

tuneip sets several parameters for the /dev/ip? devices, for better performance (or for any performance at all, if your printer 
won't work without it...). W ithout parameters, tuneip tells whether the device is using interrupts, and if so, which one. 

With parameters, tuneip sets the device characteristics accordingly. Theparametersareasfollows: 

-i <1 rq> ThelRQ to use for the parallel port in question. Ifthisissettosomethingnonzero, -t 

and -c have no effect. If your port does not use interrupts, this option will make 
printing stop, tuneip -10 restores non-interrupt driven (polling) action, and your 
printer should work again. If your parallel port does support interrupts, interrupt-driven 
printing should be somewhat faster and efficient and will probably be desirable. 

-t <t 1 me > The amount of time in jiffies that the driver waits if the printer doesn't take a character 

for the number of tries dictated by the -c parameter. 10 is the default value. If you want 
the fastest possible printing and don't care about system load, you can setthisto 0. If 
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-o [on!off] 

-C [on[off] 


-q [on|off] 


you don't care how fast your printer goes or are printing text on a slow printer with a 
buffer, then 500 (5 seconds) should be fine and will give you very low system load. This 
value generally should be lower for printing graphics than text, by a factor of approxi¬ 
mately 10, for best performance. 

The number of times to try to output a character to the printer before sleeping for 
-t <ti me >. It is the number of times around a loop that tries to send a character to the 
printer. 120 appears to beagood value for most printers 250 isthe default because there 
are some printers that require a wait this long, but feel free to change this. If you have a 
very fast printer like an H P L aserj St 4, a value of 10 might make more sense If you have 
a really old printer, you can increase this 
Setting -t <ti me > to 0 isequivalent to setting -c <chars> to infinity. 

The busy loop counter for the strobe signal. Although most printers appear to be able to 
deal with an extremely short strobe, some printers demand a longer one. Increasing this 
from the default 0 might make it possible to print with those printers This can also 
make it possible to use longer cables 

This is whether to abort on printer error; the default is not to. If you are sitting at your 
computer, you probably want to be ableto see an error and fix it and have the printer go 
on printing. 0 n the other hand, if you aren't, you might rather that your printer spooler 
find out that the printer isn't ready, quit trying, and send you mail about it. The choice 
is yours 

This option is much like -a. It makes any open 0 of this device check to see that the 
device is online and not reporting any out-of-paper or other errors. This isthe correct 
setting for most versions of ipd. 

This option adds extra ("careful") error checking. When this option is on, the printer 
driver wi II ensure that the printer is online and not reporting any out-of-paper or other 
errors before sending data. This is particularly useful for printers that usually appear to 
accept data when turned off. 

This option returns the current printer status, both as a decimal number from 0 to 255 
and as a list of activeflaga When this option isspecified, -q off, turning off the display 
of the current IRQ, is implied. 

-0, -c, and -s all requirea Linux kernel version of 1.1.76 or later. 

Thisoption resets the port. It requiresa Linux kernel version of 1.1.80 or later. 
Thisoption sets printing thedisplay of the current IRQ setting. 

CohesiveSystems 26 August 1992 


update_state 

updatejstate- U pdate system state. 

SYNOPSIS 

update_state 

DESCRIPTION 

update_state updatesa bunch of system states Ittakesa long time to execute and would be suitablefor execution in a cron 
job. 

Currently, updatejstate performs the following functions: updates the locate database (in /usr/iib/iocate), updates the 
whatis database(in /usr/man, /usr/local/man, /usr/X386/man, and /usr/interviews/man), and Updates theTeX ls-R Cache file 
(in /usr/lib/texmf). 



BUGS 

The script expects things to be where the FSSTN D saysthey are. For example if you havemakewhatis(8) in /usr/iib, where 
it istraditionally, then you lose because it should be in /usr/bin. 

SEE ALSO 

cron(8), find(l), locate(l) 

AUTHOR 

Rik Faith (faith@cs.unc.edu) 

Linux 1.0 8, July 1994 


uucico 

uucico— U U C P file transfer daemon. 

SYNOPSIS 

DESCRIPTION 

The uucico daemon processes file transfer requests queued by uucp(l) and uux(l). It isstarted when uucpor uux is run (unless 
they are given the -r option). It isalso typically started periodically using entries in the crontab tables 
When invoked with -n, --master, -s, --system, or -s, the daemon will placea call to a remote system, running in master 
mode Otherwise, the daemon will start in slave mode accepting a cal I from a remote system. Typically, a special login name 
will beset up for UUCP, which automatically invokes uucico when a call is made. 

When uucico terminates it invokesthe uuxqt{8) daemon, unless the -q or --nouuxqt option isgiven; uuxqt(8) executes any 
work orders created by uux(l) on a remote system and any work orders created locally that have received remote files for 
which they were waiting. 

If a call fails, uucico will usually refuse to retry thecall until a certain (configurable) amount of timehas passed. This may be 
overridden by the -f, -force, or -s option. 

The -l, --prompt, -e, or --loop options may be used to force uucico to produceitsown prompts of login: and Password:. 
When another daemon calls in, it will see these prompts and log in as usual. The login name and password are usually 
checked against a separate list kept specially for uucico rather than the /etc/passwd file; it is possible on some systemsto 
direct uucico to use the/etc/passwd file. The -lor -prompt option will prompt once and then exit; in this mode the UUCP 
administrator or the superuser may use the -u or - login option to force a login name in which case uucico will not prompt 
for one. The -e or -loop option will prompt again after thefirst session is over; in this mode, uucico will permanently control 
a port. 

If uucico receivesasiGQuiT, sigterm, or sigpipe signal, it will cleanly abort any current conversation with a remote system 
and exit. If it receives a sighup signal, it will abort any current conversation, but will continue to place calls to (if invoked 
with -ri or - -master) and accept calls from (if invoked with -e or--loop) other systems. If it receives a sigint signal, it will 
finish the current conversation but will not place or accept any more calls. 

OPTIONS 

Thefollowing options may be given to uucico: 

-n, ---master Start in master mode (call outto asystem); implied by -s, --system, or -s. If no system 

is specified, call any system for which work is waiting to be done. 

-r0, ---slave Start in slavemode. T his isthe default. 

-s system, ---system system Call thenamed system. 
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-p port , ---port port 




■q, - ■ -nouuxqt 


-C, - ■ -ifwork 


-D, - ■ -nodetach 


-x type, 


type, - ■-debug type 


---config file 


--help 


Call the named system, ignoring any required wait. This is equivalent to -s system -f. 
Ignore any required wait for any systems to be called. 

Prompt for login name and password using login: and Password:. This allows uucico to 
be easily run from inetd(8). The login name and password are checked against the 
UUCP password file which probably has no connection to the file /etc/passwd. The 
--login option may be used to force a login name, in which case uucico will only 
prompt for a password. 

Specify a port to call out on or to listen to. 

Enter endless loop of login/password prompts and slave mode daemon execution. The 
program will not stop by itself; you must use km(l) to shut it down. 

After calling out (to a particular system when -s, --system,or -s isspecified or to all 
systems that have work when just -ri or - -master isspecified), begin an endless loop as 
with - -loop. 

D o not start the uuxqt(8) daemon when finished. 

If no calls are permitted at thistime, then don't make the call, but also do not put an 
error message in the log file and do not update the system status (as reported by 
uustat(l)). This can be convenient for automated polling scripts, which may want to 
simply attempt to call every system rather than worry about which particular systems 
may be called at the moment. This option also suppresses the log message indicating 
that there is no work to be done. 

Only call the system named by -s, --system, or -s if there is work for that system. 

D o not detach from the controlling terminal. N ormally, uucico detaches from the 
terminal before each call out to another system and before invoking uuxqt. Thisoption 
prevents this 

Set the login name to useinstead of that of the invoking user. Thisoption may only be 
used by the UUCP administrator or the superuser. If used with - -prompt, this will cause 
uucico to prompt only for the password, not the login name 
If a call fails after the remote system is reached, try the next alternate rather than simply 
exiting. 

Sdt the type of port to use when using standard input. The only support port type is 
TLI, and this is only available on machinesthat support theTLI networking interface. 
Specifying -mi causes uucico to useTLI calls to perform I/O. 

T urn on particular debugging types. The following types are recognized: abnormal, chat, 
handshake, uucp-proto, proto, port, config, spooldir,execute, incoming, outgoing. 

M ultiple types may be given, separated by commas, and the - -debug option may appear 
multiple times A number may also be given, which will turn on that many types from 
theforegoing list; for example, --debug 2 is equivalent to -debug abnormal, chat. 

The debugging output issent to thedebugging file usually one of/usr/spooi/uucp/Debug, 
/usr/spool/uucp/DEBUG, Or /usr/spool/uucp/.Admin/audit.local. 

set configuration file to use Thisoption may not be available depending on how 
uucico was compiled. 

Report version information and exit. 

Print a help message and exit. 

Thisoption isignored. It is only included because some versions of uucpd invoke uucico 
with it. 


FILES 

T hefi lenames may be changed at compilation time or by the configuration file, so these are only approximations: 
/usr/nb/uucp/config Configuration file. 

/usr/nb/uucp/passwd Default UUCP password file. 
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/usr/spool/uucp 

/usr/spool/uucp/Log 

/usr/spool/uucppublic 

/usr/spool/uucp/Debug 


UUCP spool directory. 

UUCP log file 

Default UUCP public directory. 
Debugging file. 


SEE ALSO 

kill(l), uucp(l), uux(l), uustat(l), uuxqt(8) 

AUTHOR 

Ian Lance Taylor (ian@airs.com) 


Taylor UUCP 1.05 


vmstat 

vmstat- Report virtual memory statistics. 

SYNOPSIS 

vmstat [ -n ] [ del ay [ count ] ] 

DESCRIPTION 

vmstat reports information about processes, memory, paging, block 10, traps, and C PU activity. 

Thefirst report produced gives averages since the last reboot. Additional reports give information on a sampling period of 
length delay. The process and memory reports are instantaneous in either case. 

OPTIONS 

The -n switch causes the header to be displayed only once rather than periodically. 

del ay is the delay between updates in seconds If no delay isspecified, only one report is printed with the average values since 
boot. 

count isthe number of updates If no count isspecified and del ay isdefined, count defaults to infinity. 

FIELD DESCRIPTIONS 


Procs 


Memory 

The number of processes waiting for runtime 

The number of processes in uninterruptible sleep. 

The number of processes swapped out but otherwise runnable 
Thisfidd is calculated, but Linux never desperation swaps 

swpd 

The amount of virtual memory used (KB). 

free 

The amount of idle memory (KB). 

buff 

Theamount of memory used as buffers (KB). 

Swap 

si 

Amount of memory swapped in from disk (KB/s). 

so 

Amount of memory swapped to disk (KB/s). 
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10 


bo 

Blocks sent to a block device (block^s). 

Blocks received from a block device (blocks/s). 

System 


cs 

T he number of interrupts per second, including the clock. 

T he number of context switches per second. 

CPU (These are percentages of total CPU time.) 


1 

User time 

System time. 

Idletime. 

NOTES 

vmstat does not require special permissions. 

These reports are intended to help identify system bottlenecks. Linux vmstat does not count itself as a running process. 

All Linux blocks are currently 1KB, except for CD-ROM blocks, which are2KB. 

FILES 

/proc/meminfo 

/proc/stat 


SEE ALSO 

ps( 1) , top(l), free(l) 

BUGS 

vmstat does not tabulate the block 10 per device oi 

- count the number of system calls. 


AUTHOR 

W ritten by H enry W are(aii72@yfn.ysu .edu) 

Throatwobbler Ginkgo Labs 27Julyl994 


vipw 

vipw— Edit the password file. 

SYNOPSIS 

DESCRIPTION 

vipw edits the password file after setting the appropriate locks and does any necessary processing after the password file is 
unlocked. If the password file is already locked for editing by another user, vipw will ask you to try again later. The default 
editor for vipw is vi(l). 



ENVIRONMENT 

If the following environment variable exists, it will be utilized by vipw: 

editor The editor specified by the string, editor will be invoked instead of the default editor 

vi(l). 

SEE ALSO 

passwd(l), vi(l), passwd(5) 

HISTORY 

The vipw command appeared in BSD 4.0. 

BSD 4,16 M arch 1991 

zdump 

zdump— Time zone dumper. 

SYNOPSIS 

zdump [ -v ][-c cutoff year ] [ zonename ... ] 

DESCRIPTION 

zdump prints the current time in each zonename named on thecommand line 
T hese options are available: 


SEE ALSO 

newctime(3), tzfile(5), zic(8) 

zic 

zic — T ime zone compiler. 

SYNOPSIS 

zic [ -V ] [-d directory ] [-1 localtime ] [ -p posixrules ] 

[-L I eapsecondf 11 ename ][-s ] [ -y command ][f 11 e n a me ... ] 

DESCRIPTION 

zic reads text from the files named on thecommand line and creates the time conversion information files specified in this 
input. If a filename is-, thestandard input is read. 

T hese options are available: 

-d directory C reate time conversion information files in the named directory rather than in the 

standard directory named below. 


For each z o n e n a me on the command li ne, print the current time, the ti me at the lowest 
possible time value, the time one day after the lowest possible time value, the times both 
one second before and exactly at each detected time discontinuity, the time at one day 
less than the highest possible time value and the time at the highest possible time value. 
Each line ends with isdst=i if the given timeisDaylightSavingTimeor isdst =0 
otherwise 

C ut off the verbose output near the start of the given year. 
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Use the given time zone as local time, zic will act as if the input contained a link line of 
theform. 

U se the gi ven ti me zone's rules when handli ng PO SI X-format ti me zone environment 
variables, zic will act as if the input contained a link line of the form. 

Link t i me z o n e p o six r uI e s . 

Read leap second information from thefilewith the given name. If thisoption is not 
used, no leap second information appears in output files 
C omplain if a year that appears in a data file is outside the range of years representable 
by time(2) values 

Limit time values stored in output files to values that are the same whether they're taken 
to be signed or unsigned. You can use this option to generate SVVS-compatiblefiles. 
Use the given command rather than yearistype when checking year types. 


I nput lines are made up of fields Fields are separated from one another by any number of whitespace characters Leading 
and trailing whitespace on input lines is ignored. An unquoted sharp character (#) in the input introduces a comment that 
extends to the end of the line the sharp character appears on. W hitespace characters and sharp characters may be enclosed in 
double quotes (■) if they're to be used as part of afield. Any line that is blank (after comment stripping) is ignored. Non¬ 
blank lines are expected to be of one of three types rule lines, zone lines and link lines 
A rule line hastheform 


Rule NAME FROM TO TYPE I N ON AT SAVE LETTER/S 


For example: 

Rule US 1967 1973 - Apr lastSun 2:00 1:00 D 

The fields that make up a rule li ne are 

name Gives the (arbitrary) nameof the set of rules this rule is part of. 

from Gives the first year in which the rule applies Any integer year can be supplied; the 

Gregorian calendar isassumed. The word minimum (or an abbreviation) meansthe 
minimum year representable as an integer. The word maximum (or an abbreviation) means 
the maximum year representable as an integer. Rules can describe times that are not 
representable as time values with the unrepresentable times ignored; this allows rules to 
be portable among hosts with differing time value types. 

to Gives the final year in which the rule applies. In addition to minimum and maximum, 

the word only (or an abbreviation) maybe used to repeat the value of the from field. 
type Gives the type of year in which the rule applies If type is-, the rule applies in all years 

between from and to inclusive If type issomethingelse then zic executes the command 

yearistype year type 

to check the type of a year. An exit status of zero is taken to mean that the year is of the 
given type; an exit status of one is taken to mean that the year is not ofthegiven type, 
i n N amesthe month in which the rule takes effect. M onth names may be abbreviated. 

on Givestheday on which the rule takes effect. Recognized forms include 

5 The fifth of the month 

lastSun ThelastSundayinthemonth 

lastMon The last Monday in the month 

Sun>=8 First Sunday on or after the eighth 

Sun<=25 Last Sunday on or before the 25th 

N amesof days of the week may be abbreviated or spelled out in full. 

N ote that there must be no spaces within theoN field. 
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at Givesthetimeofdayatwhichtheruletakeseffect. Recognized forms include 

2 Time in hours 

2:00 Time in hours and minutes 

15:00 24-hour format time (for times after noon) 

1:28:14 Timein hours, minutes, and seconds 

Any of these forms may be followed by the letter w if the given time is local wall clock 
time, s if the given time is local standard time or u (or g or z) if the given timeis 
universal time; in the absence of an indicator, wall clock time is assumed. 
save Gives the amount of time to be added to local standard time when the rule is in effect. 

This field has the same format as the at field (although, of course, thew and s suffixes 
are not used). 

iftfER/s Gives the variable part (for example, thes orD in EST or EDT) of time-zone abbrevia¬ 

tions to be used when this rule is in effect. If this field is-, the variable part is null. 


A zone line has the form 

Zone NAME GMTOFF RULES/SAVE FORMAT [UNTIL] 

For example: 

Zone Australia/Adelaide 9:30 Aus CST 1971 Oct 31 2:00 

The fields that make up a zone line are 

name Thenameof thetimezone Thisisthenameused in creating the time conversion 

information filefor the zone. 

gmtoff The amount of time to add to GMT to get standard timein this zone. This field hasthe 

same format as the at and save fields of rule lines; begin the field with a minus sign if 
ti me must be subtracted from GMT. 

rules/save The name of the rules that apply in the time zone or, alternately, an amount of time to 

add to local standard time If thisfidd is-, standard time always appliesin the time 
zone. 

format Theformatfortimezoneabbreviationsin thistimezone. Thepairof characters is 

used to show where the variable part of the time-zone abbreviation goes. Alternately, a 
slash (/) separates standard and daylight abbreviations. 

unti l The time at which theGMT offset or the rules change for a location. It is specified as a 

year, a month, a day, and a time of day. If this is specified, the time-zone information is 
generated from the given GM T offset and rule change until the time specified. 

The next line must be a continuation line; this has the same form as a zone line except 
that the string zone and the name are omitted because the continuation line will place 
information starting at the time specified astheuNTi l field in the previous line in thefile 
used by the previous line. Continuation lines may contain an unti l field, just as zone 
lines do, indicating that the next line is a further continuation. 


A link line hastheform 

Link LI NK-FROM LI NK-TO 

For example: 

Link US/Eastern EST5EDT 

TheLi nk-from field should appear astheNAME field in some zone line; the li nk-to field is used as an alternate name for that 
zone. 

Except for continuation lines, lines may appear in any order in the input. 

Lines in the file that describe leap seconds have the following form: 
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Leap YEAR MONTH DAY HH: MM: SS CORR RZ5 

For example: 

Leap 1974 Dec 31 23:59:60 + S 

The year, month, day, and hh: mm: ss fields tell when the leap second happened. ThecoRR field should be + if a second was 
added or - if a second was skipped. T he r/ s field should be (an abbreviation of) stationary if the leap second time given by 
the other fields should be interpreted asGMT or (an abbreviation of) Roiling if the leap second time given by the other 
fields should be interpreted as local wall clock time 

NOTE 

For areas with more than two types of local time, you may need to use local standard time in the at field of the earliest 
transition time's rule to ensure that the earliest transition time recorded in the compiled file is correct. 

FILE 

/usr/iocai/etc/zoneinfo standard directory used for created files. 

SEE ALSO 

newctime(3), tzfile{5), zdump(8) 
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addjimer, deljimer, init_timer 

add_timer, del_timer, init_timer— M an age event timers. 

SYNOPSIS 

#include <asm/param.h> 

#include <linux/timer.h> 

extern void add_timer(struct timer_list * timer); 
extern int del_timer(struct timer_list * ti mer ); 
extern inline void init_timer(struct timer_list * timer); 

DESCRIPTION 

add_timer schedules an event, adding it to a linked list of events maintained by the kernel. dei_timer deletes a scheduled 
event, ti mer points to a 
struct timer_list { 

struct timer_list ‘prev; 
unsigned long expires; 
unsigned long data; 
void (‘function)(unsigned long); 

}; 

init_timer sdts next and prev to null. T his is required for the argument of add_timer. ex pi res isthedesired duration of the 
timer in jiffies, where there are hz (typically 100) jiffies per second. W hen the timer expires, function is called with da t a as 
its argument. It isthe responsibility of function to deldte the event. If the same function is managing several timers, the 
argument can be used to distinguish which oneexpired. 

RETURN VALUE 

dei_timer returns zero on error— if next or pr ev are not null, but the timer was not found. dei_timer also sets ex pi r es to the 
time remaining before thetimer expires and sets next and prev to null. Thus, calling dei_timer followed immediately by 
add_timer is a no-op provided a kernel tick does not occur between the two calls 

AUTHOR 

LinusTorvalds 

Linux 1.2.8, 31 May 1995 


adjust_clock 

adjust_ciock— Adjusts startup time counter to tick in G M T. 

SYNOPSIS 

linux/kernel/sys.c 
void adjust_clock(); 

DESCRIPTION 

This routine adjuststhe startup time by adding the time zone information to it. The goal is to get the startup time ticking in 
GMT time 

NOTES 

This routine iscalled from settimeofday(2) when thetimezone information isfirst set. 
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AUTHOR 

TheodoreT'SO (tytso@mit.edu) 

SEE ALSO 

settimeofday(2) 

Linux0.99.10, 7Julyl993 


ctrl_alt_del 

ctn_ait_dei- Routes the keyboard interrupt Ctrl+Alt+D el key sequence. 

SYNOPSIS 

linux/kernel/sys.c 
void ctrl_alt_del(void); 

DESCRIPTION 

This simple routine tests the variable c. a. d for a true/false condition. If it is true, a hard reset is done by the system. 
Otherwise, a signal sigint is sent to the process with the process ID 1, usually a program called imt. 

WARNINGS 

Thisroutineisin interrupt mode Itcannotsynco your system. D ata loss may occur. It is recommended that you configure 
your system to send a signal to init, where you can control the shutdown. 

NOTES 

The default of this function is to do hard resets immediately. 

AUTHOR 

LinusTorvalds 


SEE ALSO 

reboot(2), reset_hard_now(9), sync(2) 


Linux0.99.10, 6July 1993 


filejable 

me_tabie- Detailed description of thetableand table entry. 

SYNOPSIS 

From#include <linux/fs.h> 
struct file { 
mode_t fjnode; 

dev_t f_rdev; /* needed for /dev/tty */ 

off_t f_pos; 

unsigned short f_flags; 

unsigned short f_count; 

unsigned short f_reada; 

struct file *f_next, *f_prev; 

struct inode *f_inode; 
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struct file_operations *f_op; 


From linux/fs/file_table.c 
struct file *first_file; 
int nr_files = 0; 

DESCRIPTION 

T hefile table is fundamentally important to any UN IX system. It is where all open files (Linux includes closed files as well) 
are stored and managed by thekernel. For Linux, you can hardly do anything without referencing it in someway. 

Linux stores its file table as a double circular linked list. The root pointer to the "head" of this list isfirst_fiie. Also, a count 
of how many entries are in the file table is maintained, called nr_fiies. Under this scheme, the file tablefor Linux could be 
as large as memory could hold. Unfortunately, this would be unmanageable in most cases. Your computer would be in the 
kernel most of the time when processes are more important. To keep this from happening, nr_fiies is tested against nr_file 
to limit the number of file table entries. 

U N D ERSTAN D IN G TH E STRU CTU RE 0 F THE FILE TABLE 

T hefile table is organized as a double circular linked list. Imagine a circle of people with everyone facing the same direction. 
Each person isfacing so that one arm isin the circle and the other arm is outside the circle Now, if each person put hisor 
her right hand on the shoulder of the person in front of him or her and if each person touched the person behind him or her 
with hisor her left hand. You have formed two circles of arms, one inside and the other outside. The right arms represent 
pointers to the next entry (or person). The left arms represent pointers to the previous entry (or person). 

THE FILE STRUCTURE, A FILE TABLE ENTRY 

At first glance, a table entry looks quite simple. An entry contains how a file was opened, what tty device a reference count, 
pointers to other entries, pointer to v-node(thevfs i-node) filesystem-specific i-node information, and so on. 

f_mode 
00 
01 
10 
11 


AUTHOR 

LinusTorvalds 

SEE ALSO 

insert_file_f ree(9), remove_file_f ree(9), put_last_free(9) grow_files(9), file_table_init(9), get_empty_filp(9) 
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After AN Ding with o accmode, this is what bits 0 and 1 mean: 

No permissions needed 
Read-permission 
Write-permission 
Read-write 

It is used only with tty lines. It containsthe major and minor numbers of the tty device 
The current position in afile if meaningful. 

Storagefortheflagsfrom openo and tcntio 
Reference counter 

This is a Boolean variable where True means that an actual read is needed. 

Pointers to other entries 

Pointer to v-node and filesystem-specific i-node information 
Pointer to a file's operations 
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file_table_init 

fiie_tabie_init— Initializes the file table in the kernel. 

SYNOPSIS 

linux/fs/file_table.c unsigned long file_table_init( 
unsigned long start , unsigned long end); 

DESCRIPTION 

This routine is called from kernei_start() in linux/init/main.c. It sets first_f iie, a struct file pointer, to NULL. This is the 
head of the linked list of open files maintained in the kernel, the infamous file table in all UN IXs 

RETURN VALUE 

Returns start. 

NOTES 

Because this is part of the kernel's startup routine, it has the option to allocate memory, in kernel space for itself. It does not 
need to do this and returnsthe new start of memory for the next initializing section. In this case start is returned unmodi¬ 
fied. 

AUTHOR 

LinusTorvalds 

Linux 0.99.10, 9 July 1993 


filesystems 

filesystems— Details the table of configured filesystems 

SYNOPSIS 

linux/fs/filesystems.c 
From ((include <linux/fs.h> 
struct file system type { 

struct superblock *(*read_super) (struct superblock *, void *, int); 



DESCRIPTION 

This source code makes a data structure call fiie_systems[ ], which contains all the configured filesystemsfor the kernel. It is 
used primarily in iinux/f s/super, c for many of the mounting of filesystems functions 

THEMEANINGS 

Thisfirst member, in struct f i i e.system.type, isa function pointer to a routine that will read i n the super_bi ock.A 
super, bi ock generically means an i-node or special place on the device where information about the overall "filesystem is 
stored. 

The name isjust the string representation of the name of a specific filesystem, such asext2 orminix. 

Thefinal member, i nt.requi res. dev, isa Boolean value. If it is True, then thefilesystem requires a block device For False, it 
is unclear what happens but an unnamed device is used, such as proc and nf s. 
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AUTHOR 

LinusTorvalds 


Linux 0.99.10,12 July 1993 


get_empty_filp 

get_empty_fiip— Fetches an unreferenced entry from the file table. 

SYNOPSIS 

linux/fs/file table.c 

struct file *get_empty_filp(void); 

DESCRIPTION 

This routine will seek out an entry that is not being referenced by any processes If none are found, then it will add new 
entries to thefile table minimum of nr_file entries 

NOTES 

Due to grow_fiieso, awholepageof entries iscreated at onetime. Thismay make more than nr_file entries Also when an 
unreferenced entry is found, it is moved to the "end" of the file table. This heuristic is used to speed up finding unreferenced 
entries. 

RETURN VALUE 

null— No entries were found and the file table isfull. 

Returnsa pointer to the entry in thefile table 

AUTHOR 

LinusTorvalds 

SEE ALSO 

grow_files(9) 

Linux0.99.10,12 July 1993 


growjiles 

grow_f nes— Adds entries to the file table. 

SYNOPSIS 

linux/fs/file table.c 
void grow_files(void); 

DESCRIPTION 

Thisfunction adds entries to the file table First, it allocates a page of memory. It fills the entire page with entries, adding 
each to the file table. 

AUTHOR 

LinusTorvalds 



inaert_ file_ free 


SEE ALSO 

insert_file_free(9), remove_file_free(9), put_last_free(9) 


Linux 0.99.10,12 July 1993 


injroupj 

in_group_p — Searches group IDsfora match. 

SYNOPSIS 

linux/kernel/sys.c 

int in_group_p(gid_t grp); 

DESCRIPTION 

Searches supplementary group ID s and the effective group ID for a match with grp. 

RETURN VALUE 

ReturnsTrue (i) if found; otherwise, false (0). 

AUTHOR 

LinusTorvalds 

SEE ALSO 

getgroups(2), getgid(2), getregid(2), setgid(2), setregid(2), setgroups(2) 
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insert_file_free 

insert_fiie_f ree— Adds a fi le entry i nto the fi le table. 


SYNOPSIS 

linux/fs/file_table.c 

static void insert_file_free(struct file ‘file); 


DESCRIPTION 

This nightmare of pointers adds f i e into the file table with the root pointer at fii e. Thisisa building block of thefile table 
management. 

AUTHOR 

LinusTorvalds 

SEE ALSO 

file_table_init(9), remove_file_free(9), put_last_free(9) 

See f iie_tabie(9) for details on the file table structure. 


Linux 0.99.10 
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kernel_mktime 

kernei_mktinie— Convert startup struct mktime into the number of seconds since 00:00:00 J anuary 1,1970. 

SYNOPSIS 

linux/kernel/mktime.c 

long kernel_mktime(struct mktime * time); 

DESCRIPTION 

This routine is called from time_init(void), unux/init/main.c. kernei_mktime() converts struct mktime (initialized from 
CMOS) into an encoded long. 

CONVERSION METHOD 

First an array, month[i 2 ], is created, holding how many seconds have passed to reach a peculiar month for a leap year. Next, 
it subtracts 70 from the current year, making 1970 the beginning year. It is math magic after this point; please look yourself. 
If you know why it does this, then send e-mail (seenrott source). 

RETURN VALUE 

Returns the encoded timein along. 

FILES 

linux/kernel/mktime.C homeof routine 

NOTES 

This routine iscalled only during startup of the kernel. 

Historically, the value (encoded long) counts the number of secondssince the Epoch, which occurred at 00:00:00 January 1, 
1970, and iscalled Coordinated Universal Time(UTC). In older manuals, this event iscalled Greenwich Mean Time 
(GMT). 

WARNINGS 

kernei_mktime () doesn't check to see if the year isgreater than 1969. Besureyour CM OS isset correctly. It is customary to 
set on-board clocks to GMT and let processes who ask for the time to convert it to local time, if necessary. 

RESTRICTIONS 

For kernel use only. 

AUTHOR 

LinusTorvalds 

Linux0.99.10, 5July 1993 


proc_sel 

proc_sei— Select a process by a criterion. 

SYNOPSIS 

linux/kernel/sys.c 
//include <linux/resource.h> 

static int proc_sel(struct task_struct *p, int which, int who); 



DESCRIPTION 

Compares a task p to supplied information or the current task in some aspect of priority. If who is zero, thecomparison is task 
p and the current task. Otherwise, who and *p are the supplied information for the comparison. 

OPTIONS 

Valid values of whi ch: 

PRIO_PROCESS 

PRIO_PGRP 
PRIO_USER 

RETURN VALUE 

Returns truth values (a, i). 


Compares process ID numbers There is an exception here. If who isnot zero and task p is 
the current task, then True is always returned. 

Compares process group leader numbers. 

C ompares user ID numbers 


AUTHOR 

LinusTorvalds 


SEE ALSO 

sys_setpriority(2), sys_getpriority(2) 
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put_file_last 

put_fiie_iast— M oves a file to the "end" of the file table. 

SYNOPSIS 

linux/fs/file table.c 

static void put_last_free(struct file *file); 


DESCRIPTION 

Thisfunction will removef i i e from thefile table and insert it again at the end. You can access by 

first_file->prev 


AUTHOR 

LinusTorvalds 

SEE ALSO 

insert_file_free(9), remove_file_free(9) 

Linux 0.99.10,11 July 1993 


remove_file_free 

remove_fiie_f ree— Removeafiletableentry from the linked list. 

SYNOPSIS 


linux/fs/file table.c 

static void remove_file_freefstruct file ‘file); 
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DESCRIPTION 

This routine removes the file from thetable This is used mostly for moving a file to the "end" of the list. 

AUTHOR 

LinusTorvalds 

SEE ALSO 

insert_file_free(9), put_file_last(9) 



Index 




■ * (adteridc), bade special parameters 


Symbols 


* (asterisk), bash special 
parameters, 15 

@ (at sign), bash special 
parameters, 15 
\ (backslash), bash escape 
character, 14 
$ (dollar sign) 

bash special parameters, 15 
expansion, 19 
ftp command, 148 
! (exclamation point) 

bash special parameters, 15 
ftp command, 148 
! command (telnet), 512 
> (greater than sign), 
redirection operator, 21 
■ (hyphen), bash special 
parameters, 15 
< (lessthan sign), redirection 
operator, 21 
| (pipeline), bash, 12 

# (pound sign) 

bash comments, 14 
bash special parameters, 15 
? (question mark) 

bash special parameters, 15 
ftp command, 152 
? command 
telnet, 512 
xauth, 591 

_ (underscore), bash special 
parameters, 15 
/ directory, 1236 
0, bash special parameter, 15 
8859-1 character set, 1064 
8859-2 character set, 1064 
8859-3 character set, 1064 
8859-4 character set, 1064 
8859-5 character set, 1065 
8859-6 character set, 1065 
8859-7 character set, 1065 
8859-8 character set, 1065 
8859-9 character set, 1065 
8859-10 character set, 1065 
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Abekas YU V bytes, converting 
to portable pixmaps, 731 
abort() function, 892 
abs() function, 892-893 
absolute values, 892-893 
floating-point numbers, 919 
long integers, 960-961 
accept, 740-741 
access, 741-742 
errors, 741 
restrictions, 741 
return value, 741 
access control 

files, changing permissions, 
61-62 

hosts_ access, 1133-1136 
diagnostics 1136 
files 1133,1136 
operators 1134 
patterns 1133-1134 
remote username lookup, 
1134-1135 
rules 1133 
diell commands 1134 
wildcards 1134 
language extensions, 
1137-1139 
memory, 804-805 
NNTP sites, 1167-1168 
account (ftp command), 148 
acct, 742 

acos() function, 893 
acosh() function, 893-894 
active^ 1104-1105 
active.times, 1104-1105 
add (cvs command), 96 
AD D_AD DRESS environ¬ 
ment variable, 529 
add_ timer, 1424 
addftinfo, 2 
addgroup, 1258-1259 
addmntent() function, 
935-936 


addresses 

Internet, manipulating, 
953-954 

mail addressing, 1244-1246 
abbreviations 1245 
case sensitivity, 1245 
compatibility, 1245 
postmasters 1246 
routing, 1245 
physical, accessing, 818 
sed, 476 

virtual memory, remapping, 
805-806 

adduser, 1258-1259 
adduser.conf, 1105 
adjtimex, 742-743 
adjust, clock, 1424-1425 
admin (cvscommand), 96 
advisory locks, open files 
(applying/removing), 757 
afmtodit, 2-4 
files, 3 
options, 3 
running, 3 
agetty, 1259-1262 
arguments, 1260 
bugs, 1261 
diagnostics, 1261 
files, 1261 
issue escapes, 1261 
options, 1260 
alarm, 744 

alarm clock, setting, 744 
alias (shell command), 35 
aliases, 23-24,1106 
bugs, 1106 
printing, 35 
removing names, 45 
alloca function, 894 
bugs, 894 
return values, 894 
allocating memory, 894, 976 
allow-null_ globexpansion 
variable (bash), 17 
allow-send-events() action 
(xterm), 714 




awk ■ 


alphasort() function, 
1012-1013 

American Standard Code for 
Information, seeASC 11 
Andrew Toolkit raster objects, 
converting to portable 
bitmaps, 10 
ANSI C, converting to 
Kernighan & Ritchie, 4 
ansi2knr, 4 

antialiasing portableanymaps, 
381-382 
anytopnm, 4 

append (ftp command), 148 
application resources, 
printing, 5 

applications (client), listing, 
669-670 
appres, 5 
ar, 5-7 

copying, 7 
modifiers, 7 
options, 6-7 

arc cosines, 893 
arc sines, 894-895 
arc tangents, 896 

two variables, 896-897 

arch, 8 

archive, 1262-1263 
archives 

creating, 5-7 
extracting from, 5-7 
indexes (generating), 
437-438 
modifying, 5-7 
shell, creating, 484-487 
arguments 

concatenating, 37 
outputting, 36-37 
reading from standard input, 
586-587 
arithmetic 
evaluation 
bash, 34 

let command, 39 
expansion, bash, 20 


functions 
awk, 168-169 
sn(), 1020-1021 
anh(), 1021 
sjrtf), 1023 
tan(), 1047-1048 
tanh(), 1048 
performing on portable 
anymaps, 382-383 
arp, 1263 

ARP cache, manipulating, 
1263 
arrays 

awk, 164 

linear searches, 975-976 
searching sorted, 900-901 
sorting, 1000 

articles (news), see tin 
as, 8-9 

ASCII (American Standard 
Code for Information), 1064 
character set, 1214-1216 
graphics, converting to 
portable graymap, 10 
ascii (ftp command), 148 
ascii manual page, 1214-1216 
asciitopgm, 10 
asctime, 984-986 
asctime() function, 910 
asin() function, 894-895 
errors, 895 
return value, 895 
asinh() function, 895 
assemblers, as, 8-9 
assert() function, 895-896 
asterisk (*), bash special 
parameters, 15 
at sign (@), bash special 
parameters, 15 
atan() function, 896 
atan2() function, 896-897 
atanh() function, 897 
Atari compressed Spectrum 
files, converting to portable 
pixmaps, 494 
Atari D egas PI 1 files, 
converting to portable 
pixmaps, 378 


Atari Degas PI3 files, 
converting to portable 
bitmaps, 379 

Atari uncompressed Spectrum 
files, converting to portable 
pixmaps, 495-496 
atexit() function, 897-898 
errors, 898 
return value, 898 
atktopbm, 10 
atobm, 49-57 
options, 50 
atof() function, 898 
atoi() function, 898-899 
atol() function, 899 
attributes, filet 59 
authentication 
cidentd, 69-70 
Kerberos authentication, 

461 

pcnfsd, 1355-1356 
pppd, 1366-1367 

authority files (X), xauth 
utility, 587-592 
auto resume variable (bash), 
18“ 

AutoCAD slide files, convert¬ 
ing to portable pixmaps, 
490-491 

AUTOSUBSCRIBE environ¬ 
ment variable, 529 
AUTOUNSUBSCRIBE 
environment variable, 530 
awk 

actions, 165-166 
arithmetic functions, 
168-169 

control statements, 167 
fields, 163 
functions, 170 
GNU extensions, 171 
historical features supported 
by gawk, 172 
I/O statements, 167 
operators, 166-167 
patterns, 165-166 
printf statement, 167-168 


■ awk 


program execution, 162-163 
regular expressions, 166 
sprintf() function, 167-168 
string constants, 169-170 
string functions, 169 
time functions, 169 
variables, 163-165 
arrays 164 
built-in, 163-164 
typing and convert on, 
164-165 

B 


backslashes (\), bash escape 
character, 14 
badblocks, 1264 
banner, 1210 
bash 

aliases, 23-24 
arguments, 11 
arithmetic evaluation, 34 
blanks, 12 
bugs, 46 

command execution, 25 
comments, 14 
compound commands, 13 
case, 13 
1st, 13 
while, 13 

control operators, 12 
environments, 25-26 
escape character, 14 
exit status, 26 
expansion, 18-21 
arithmetic, 20 
brace 19 

command substitution, 20 
history, 33-34 
parameter, 19-20 
pathname 21 
processsubstitution, 20 
quote removal, 21 
tilde 19 

word splitting, 21 
files, 46 
functions, 23 


history list, 32-33 
invocation, 45-46 
job control, 24-25 
lists, 12-13 
meta characters, 12 
names, 12 
options, 11 
parameters, 14-15 
positional, 14 
special, 14-15 
pipelines(|), 12 
prompting, 26 
quoting, 14 
readline 27-32 
commands 29-32 
controlling kgr bindings 
27 

customizing 27 
denoting keyiroke $ 27 
macro definitions 28 
parser directives 28-29 
variables 28 
redirection, 21-23 

duplicating file descriptors 
23 

heedocuments 22-23 
input, 22 

opening file descriptors 23 
opeators 21 
output, 22 

standard error output, 22 
standard output, 22 
reserved words, 12 
shell variables, 15-18 
allow- 

null_glob_expanson, 17 
auto_ resume, 18 
BASH,15 

BASH VERSION, 15 
cdable_vars 18 
CDPATH, 16 
command_oriented_history, 
17 

EN V, 16 
EUID,15 
FCED IT, 17 
FIGNORE, 17 


glob_dot_filenames 17 
hi debars 17-18 
HISTCM D, 16 
HISTFILE, 17 
HISTFILESIZE, 17 
hi story control, 17 
HIST SIZE, 17 
HOME, 16 

hostname_ compldtion_ file, 
18 

HOSTTYPE, 16 
IFS, 16 

IGNOREEOF, 17 
INPUTRC, 17 
LINEN 0,15 
MAIL, 16 

MAIL_WARNING, 16 
MAILCHECK, 16 
MAILPATH, 16 
no_ ecit_ on_ failed_ exec, 

18 

noclobbe, 18 
nolinks 18 
notify, 17 
OLDPWD, 15 
OPTARG,16 
OPTERR, 17 
OPTIND, 16 
OSTYPE, 16 
PATH,16 
PPID.15 

PROM PT_COMM AND, 
17 

PS1,16 
PS2,16 
PS3,17 
PS4,17 
PWD, 15 
RANDOM, 15 
REPLY, 15 
SECONDS, 15 
SHLVL, 15 
TMOUT, 17 
UID,15 
signals* 25 

simple commands, 12 
words, 12 
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BASH variable (bash), 15 
BASH VERSION variable 
(bash), 15 

bcmp() function, 899-901 
bcopy() function, 900-901 
BDF fonts, generating, 
146-147 

bdflush, 744-745 
errors, 745 
return value, 745 

bdftopcf, 47 
beforelight, 47-48 
bell (ftp command), 148 
bell() action (xterm), 713 
bell-style variable (readline), 
28 

Bennet Yee face files, see face 
files 

Bentleyizing portable 
graymaps, 369 
Bessel functions, 959-960 

j0(), 959 
jl(), 959 
jn(), 959 
y0(), 959 
yl(), 959 
yn(), 959 

bg (shell command), 35 
bibliographic databases, 219 

fields, 219 

inverted indexes, 209-210 
searching, 210, 292-293 

biff, 48 

biff server, 1274-1275 
/bin directory, 1236 
binary (ftp command), 148 
binary dates/times, converting 
to ASCI I, 909-911 
binary files, encoding/ 
decoding, 565-566 
binary streams, input/output 
(getting), 926-927 
binary trees 

deleting items, 1056 
searching, 1056 
traversing, 1056 


bind, 35, 745-746 

errors, 745-746 
return value, 745 

binding names to sockets, 
745-746 

bioradtopgm, 48-49 

bugs, 49 
options, 49 

bit sets, finding first in words, 
921 

Bitmap Distribution Format 
fonts, converting to Portable 
Complied Format, 47 
bitmap widget, 56-57 
bitmaps, 49-57 
CM U, con verting to 
portable, 71 
color, 56 
conversion, 49 
cutting and pasting, 54 
display, 50 

drawing commands, 51-53 
Edit menu commands, 

53-54 

editing images, 50-51 
File menu commands, 53 
options, 49-50 
Universal Product Code, 
creating, 368 
widgets, 54-56 
blanks (bash), 12 
block buffered streams, 1016 
block special files, creating, 
325 

BMP files, converting to 
portable pixmaps, 57 
bmptoppm, 57 
bmtoa, 49-57 
/boot directory, 1236 
boot-time parameters 
(kernel), see bootparam 
bootparam, 1216-1224 
Adaptec configurations, 
1219-1220 

argument list, 1216-1217 
BusLogic configuration, 

1220 


busmouse driver parameters, 
1224 

CD-ROM parameters, 
1222-1223 

debug argument, 1217 
Ethernet device parameters, 

1223 

floppy disk driver param¬ 
eters, 1223-1224 
future domain configura¬ 
tion, 1220 

hard disk parameters, 
1220-1221 

mem=argument, 1218 
no-hit argument, 1217 
no387 argument, 1217 
Pro Audio configuration, 
1220 

ramdisk= argument, 1218 
reboot=warm argument, 
1218 

reserve= argument, 

1217- 1218 

ro argument, 1217 
root= argument, 1217 
rw argument, 1217 
SCSI device arguments, 

1218- 1219 

SCSI tape configuration, 

1219 

Seagate ST-Ox configuration, 

1220 

sound driver parameters, 

1224 

T rantor T128 configuration, 
1220 

Bourne shell, see sh 
Bourne-again shell, see bash 
brace expansion, 19 
break (shell command), 35 
brk, 746 

browsers, lynx, 306-309 
commands, 308-309 
options, 306-308 

brushtopbm, 57 

bsearch() function, 900-901 
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buffchan, 1264-1265 

drop command, 1265 
flush command, 1265 
readmap command, 1265 

buffer-dirty-flush daemon, 
744-745 

buffering streams, 1016-1017 
buffers 

caches committing to disk, 
869 

filesystem, flushing, 
1401-1402 

flushing from files to disk, 
756-757 
kernel log, 873 
kernel message ring, reading/ 
clearing, 872-874 
multiple, reading/writing 
data, 1003-1004 
BUG_AD DRESS environ¬ 
ment variable, 529 
buildhash, 274, 279 
files, 281 

builtin (shell command), 35 
busmouse drivers, boot-time 
parameters, 1224 
bye (ftp command), 148 
byte strings 

comparing, 899-900 
copying, 900 
operations, 901 
writing zeros to, 902 
bytes 

counting (in files), 70 
swapping adjacent, 1043 

bzero() function, 901-902 

c 


c 

converting AN SI to 
Kernighan & Ritchie, 4 
functions, displaying 
headers, 455-456 
preprocessors, 81-84 
imaket 264-261 
options 82-84 


string table source files/ 
headers, 314-315 
see a/so gcc 

C++compiler, seeg++ 
cacheflush, 746-747 

bugs, 747 
errors, 747 
return value, 747 

caches (ARP), manipulating, 
1263 

CAdose routine, 964 
cal, 58 

calendar sheets, seegcal 
C Alistopen routine, 964 
calling up systems, 88-90 
callocf) function, 976 
canonicalized absolute 
pathnames, 1004-1005 
CAopen routine, 964 
case 

bash command, 13 
ftp command, 148 

cat, 58-59 

catdose() function, 903-904 
catgets() function, 902-903 
catopen() function, 903-904 
cccp, 81-84 

copying, 84 
options, 82-84 

cd 

ftp command, 148 
shell command, 35-36 

CD-ROMs, boot-time 
parameters, 1222-1223 
cdable vars variable (bash), 
18 

CD PATH variable (bash), 16 
cdtin, 516 

see a/so tin 

cdup (ftp command), 148 
ceil() function, 904 
cfdisk, 1265-1269 

bugs, 1269 

commands, 1267-1268 
options, 1268-1269 

cfgetispeed() function, 877, 
1053 


cfgetospeed() function, 877, 

1052 

cfingerd, 1106-1109 

bugs, 1108 
error messages, 1108 
features, 1107-1108 
options, 1106-1107 
SYSLOG messages, 1108 
text commands, 1115 
cfingerd .conf, 1109-1115 
display files section, 
1109-1110 

finger display configure 
section, 1110-1111 
finger fake users files section, 
1114 

finger programs files section, 
1114 

finger strings configure 
section, 1113 
forwarded host section, 

1112 

internal config configure 
section, 1111-1112 
internal strings configure 
section, 1113 
rejected host section, 1112 
services header configure 
section, 1114 

services positions configure 
section, 1114-1115 
signal strings configure 
section, 1113-1114 
system list sites configure 
section, 1112 
trusted host section, 1112 
cfmakeraw() function, 1052 
cfsetispeed() function, 877, 

1053 

cfsetospeed() function, 877, 

1052-1053 

character sets, 1064-1066 

ASCII, 1064,1214-1216 
ISO 2022,1066 
ISO 4873,1066 
ISO 8859,1064-1065 
ISO 8859-1,1239-1242 
alphabets 1240 
characters 1240-1242 
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K0I8-R, 1065 
Unicode, 1065,1253-1255 
combining characters 
1254 

implementation levels 
1254 

character special files, 
creating, 325 
characters 

classifying, 957-958 
converting 
to ASCII, 1055 
wide to multi byte, 
1061-1062 

locating in strings, 953, 
1029 

multibyte, converting to 
wide characters, 978 
outputting, 997-999 
returning number of bytes 
in, 977 

searching strings for sets, 
1035-1039 
translating/deleting, 
536-539 

chat, 727-730,1269-1273 

abort strings, 1270-1271 
Boolean options, 729 
daemons, 727 
escape menu, 728 
escape sequences, 
1271-1272 
options, 1269-1270 
readdressing, 729 
report strings, 1271 
runtime options, 728-729 
script, 1270 
startup file 729 
termination codes, 1272 
timeout value 1271 
username field, 727 
Xll interface, 730 
chattr, 59-60 
chdir, 747-748 
checkout (cvs command), 
96-97 

checksums, computing on 
files, 501 


chfn, 60 
chgrp, 61 

child processes, creating, 751, 
758 

chkdupexe 61 

chmod, 61-62,148,748-749 

errors, 749 
operators, 62 
options, 62 
return value, 748 
specifying mode 748 
chooser (xdm), 607 
chown, 62-63, 749-750 
errors, 749-750 
options, 63 

chroot, 750-751,1273 

errors, 750-751 
return value, 750 

chsh, 63 
ci, 64-69 

controlling file access, 67 
diagnostics, 68 
environment, 68 
file modes, 67 
options, 65-66 
setuid privileges, 67-68 
specifying files, 66-67 
temporary files, 67 
cidentd, 69-70 
cksum, 70 
clear, 70-71 

dear-saved-lines() action 
(xterm), 715 

dearerr function, 919-920 
clearing terminal screen, 
70-71 

dientlib, 904-905 
clients 

listing running applications, 
669-670 

Remote Start, see rstart 
X, killing, 666-667 

clipboards, X client, 595-597 

buttons, 596 

sending/retrieving contents, 
596-597 


clock, 344,1273-1274 

colors, 344 
options, 1273 
xdock, 593-595 

dock() function, 905 
clocks 

alarm, setting, 744 
CMOS, 1273-1274 
kernel, adjusting, 742-743 

clone, 751 
close, 752 

ftp command, 148 
telnet command, 508 

dosedir() function, 905-906 
doselog() function, 
1045-1046 

CloseOnExec routine, 965 
CM OS clock, 1273-1274 
CMU bitmaps converting to 
portable, 71 
cmuwmtopbm, 71 
co, 71-75 

diagnostics, 75 
environment, 75 
file modes, 75 

keyword substitution, 74-75 
limitations, 75 
options, 72-74 

col, 76 
colcrt, 77 

color, bitmap application, 56 
colrm, 77-78 
column, 78 
columns 

formatting lists into, 78 
removing from files, 77-78 

comm, 78-79 

options, 79 

command (shell command), 
36 

command-line options, 
parsing, 937-940 
command_ oriented_ hi story 
variable (bash), 17 
commands 

bitmap application 
drawing, 51-53 
Edit menu, 53-54 
File menu, 53 


■ commands 


building/executing from 
standard input, 586-587 
cu, 88-89 
cvs, 91-104 
editres, 121-122 
execution, bash, 25 
exit status, 26 
ftp, 148-152 
gpic, 212-213 
history lists, displaying, 39 
info, 269-270 
ispell, 274-275 
locating sourc^binary and 
manualsfiles, 575-576 
I pc, 1317-1318 
lynx, 308-309 
more, 328 

nslookup, 1351-1353 
options, parsing, 207-208 
RCS, 447-449 
readline library, 29-32 
redirection, 21-23 

duplicating file descriptors 
23 

here-documents 22-23 
input, 22 

opening file descriptors 23 
operators 21 
output, 22 

standard error output, 22 
standard output, 22 
remote execution, 569-571 
sed, 478-479 
grouping, 478 
syntax, 476 
shell (built-in), 35-45 
enabling/disabling, 37 
hdp information, 38 
telnet, 508-512 
tftp, 514 
timedc, 1409 
tin 

article viewer, 522-524 
editing, 519 

global options menu, 524- 
525 

group index, 521-522 


newsgroup station, 
519-520 

pool directory selection, 
520 

thread listing, 522 
top, 534-535 
xauth, 588, 591 
zmore, 733-734 

comment-begin variable 
(readline), 28 
comments 

bash, 14 
sed, 477 

commit (cvs command), 

96-98 

comparing 

files, 78-79 

compressed, 731-732 
strings, 1029-1030 
ignoring case, 1028 
usng current locale 1030 
compilers 

g4+, 155-160,174-201 
bugs 160 
copying, 160, 201 
filename suffixes 174-175 
files 159-160, 200 
options 155-159, 
175-178 

pragmas 159, 200 
gcc, 174-201 

assembling output, 8-9 
bugs 201 
copying, 201 

filename suffixes 174-175 
Hies 200 
options 175-178 
pragmas 200 
rpcgen, 464-466 
compiling, make utility 
(recompiling programs), 
310-312 

completion-query-items 
variable (readline), 28 
compound commands (bash), 
13 


compressed files 

comparing, 731-732 
compressing/expanding, 
248-252 

executable files 252-253 
searching for regular 
expressions, 733 
viewing text, 733-734 

comsat, 1274-1275 

concatenating 

files, 58-59 
compressed, 251 
portable anymaps, 383 
strings, 1028-1029 

C oncurrent Versions System, 
see cvs 

conditional expressions, 
evaluating, 43 

configurable fi nger daemon, 
1106-1109 

configuration file, 
1109-1115 
display files section, 
1109-1110 
finger display configure 
section, 1110-1111 
finger fake users files 
section, 1114 
finger programs files 
section, 1114 
finger strings configure 
section, 1113 
forwarded hoi section, 
1112 

internal config configure 
section, 1111-1112 
internal stringsconfigure 
section, 1113 
rqected host section, 1112 
services header configure 
section, 1114 
services positions configure 
section, 1114-1115 
sgnal stringsconfigure 
section, 1113-1114 
ystem liststesconfigure 
section, 1112 
trusted host section, 1112 
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error messages, 1108 
features, 1107-1108 
SYSLOG messages, 1108 

configuration information, 
getting at runtime, 
1043-1045 
configuring 

network i nterfaces, 
1304-1305 
rstartd, 469 
keywords, 470 
serial ports, 1394-1395 
SF86_SVGA servers, 
627-628 

SF86_VGA16 servers, 631 
system logging file, 
1402-1403 
tinrc, 525-526 
XF86_Accel servers, 

615-616 

XF86_M ono servers, 624 
XFree86, 636 
xfs, 642 

xinetd, 656-660 

confstrf) function, 906-907 
connect, 752-753 
connections 

dialup IP, handler, 
1285-1288 

displaying active, 1339-1342 
routing information, 1341 
socket information, 
1340-1341 

displaying active routing 
information, 1341 
full-duplex, shutting down, 
855 
socket 

accepting, 740-741 
initiating, 752-753 
listening for, 792-793 

console, 1066-1067 
console, codes, 1067-1074 

character sets, 1072 
control characters, 1068 
CSI sequences, 1069-1070, 
1074 


display attributes, 
1070-1071 

ESC sequences, 1068-1069, 
1073-1074 
mode switches, 1071 
mouse tracking, 1072-1073 
private CSI sequences, 1072 
Set/Reset M ode sequences, 
1071 

status report commands, 
1071 

console, ioctls, 1074-1080 
consoles 

control-character handling, 
1073 

properties, 1067 
sequences, 1067-1074 
character sets 1072 
control characters 1068 
CSI, 1069-1070,1074 
display attributes 
1070-1071 
ESC, 1068-1069, 
1073-1074 
modeswitches 1071 
mouse tracking, 
1072-1073 
private CSI, 1072 
Set/ResetM ode 1071 
status report commands 
1071 

starting processes on, 1066 
switching, 1067 
virtual, 1066 

memory, 1101-1102 

continue (shell command), 36 
control messages, 1310 
control operators (bash), 12 
control statements, awk, 167 
control.ctl, 1115-1116 
controlling terminal, getting 
name, 909 
convdate, 79 

conversational exchanges, 
1269-1273 

abort strings, 1270-1271 
chat script, 1270 
escape sequences, 

1271-1272 


report strings, 1271 
termination codes, 1272 
timeout value 1271 
convert-meta variable 
(readline), 28 
converting 

Abekas YU V bytes to 
portable pixmaps, 731 
Andrew T oolkit raster 
objects to portable 
bitmaps, 10 

ANSI C to Kernighan & 
RitchieC, 4 

ASCII graphicstoportable 
graymap, 10 
Atari files 

compressed Spectrum files 
to portable pixmaps 494 
DegasPIl filestoportable 
pixmaps 378 
DegasP 13 filesto portable 
bitmaps 379 
uncompressed Spectrum 
filesto portable pixmaps 
495-496 

AutoCAD slide filesto 
portable pixmaps, 490-491 
Bennet Yee face files to 
portable bitmaps, 726 
Biorad confocal filesto 
portable graymaps, 48-49 
bitmap files, 49 
CMU to portable 71 
to portable pixmaps 57 
characters 
to ASCII, 1055 
wide to multi byte 
1061-1062 
dates/times, 79 
to ASCI I, 984-986 
to D iscordian format, 
1210-1211 

documents, troff to LaTeX, 
1252-1253 
doodle brush files to 
portable bitmaps, 57 
FITS files to portable 
anymaps, 142-143 
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fonts 

Bitmap D istribution 
Format to Portable 
Compiled Format, 47 
packed format to portable 
bitmaps 381 

GEM IM G files to portable 
bitmaps, 201 
GIF files to portable 
anymaps, 208-209 
Gould scanner files to 
portable pixmaps, 211 
groff output to TeX dvi 
format, 227-228 
G roup 3 fax files to portable 
bitmaps, 160-161 
HI PS files to portable 
graymaps, 256 
H P PaintJet files to portable 
pixmaps, 381 
ILBM files to portable 
pixmaps, 263-264 
image file to portable 
anymap, 4 
Img-whatnotfilesto 
portable pixmaps, 267 
letters 

to lowercase 1055-1056 
to uppercase, 1055-1056 
Lisp machine bitmap files to 
portable graymaps, 292 
M acintosh PICT files to 
portable pixmaps, 379-380 
M acPaint files to portable 
bitmaps, 309-310 
MGR bitmaps to portable 
bitmaps, 322-323 
multibyte characters to wide 
characters, 978 
multibyte strings to wide 
character, 977-978 
object code into N LM 
outfiles, 338-339 
PCX files to portable 
pixmaps, 368-369 
Photo-CD files to portable 
pixmaps, 260-261 


portable anymaps 
toDDIF format, 396 
to FITS format, 396-397 
to PostScript, 397 
to SGI image file 
398-399 

to Solitaire format, 399 
to Sun raster files 398 
toTIFF files 399-400 
intoXll window dumps 
400 

portable bitmaps 

to Andrew T oolkit raster 
objects 358 
to ASCI I graphics 357 
to Atari Degas PI 3 files 
364 

to BennetYee " face" files 
367 

to BitGraph graphics 358 
toCMU window manager 
bitmaps 358-359 
to compressed G raphO n 
graphics 360-361 
to DEC LN 03+Sixel 
output, 362 

to encapsulated PostScript- 
style bitmaps 359 
to Epson printer graphics 
359 

to GEM IMG files 360 
to Gemini lOx graphics 
356 

to Group 3 fax files 360 
to HP LaserJet format, 
361-362 

to M acPaint files 363 
to MGR bitmap, 363 
to packed format fonts 

364- 365 

to portable graymaps 364 
to PostScript, 362 
to Printronix printer 
graphics 366 
to Sun icons 361 
to UNIX plot files 

365- 366 


toXlO bitmaps 366 
toXll bitmaps 367 
to Zinc bitmaps 367-368 
portable graymaps 
to L isp machine format, 
376-377 

to portable bitmaps 377 
to portable pixmaps 378 
toUsenixFaceSaver 
format, 376 
portable pixmaps 

to Abekas YU V files 428 
to Atari Degas PI 1 files 
422 

to AutoCAD, 414-416 
to BMP files 416 
to DEC sixel format, 
425-426 

to GIF files 416-417 
to HP PaintJet files 423 
to HP PaintJet XL PCL 
files 424 

to ILBM files 418-419 
toMacintodi PICT files 
422-423 

toM itsubidii S340-10 
files 420-421 
toMotifUIL icon files 
427 

to NCSA ICR format, 
417-418 
to PCX files 421 
to portable graymaps 
421-422 

to red/blue 3D glasses 
400-401 

to three portable graymaps 

425 

to three raw YUV files 
428-429 

to T rud/ision T arga files 

426 

toXll pixmaps 427-428 
toXll puzzle files 
424-425 

PostScript files to portable 
anymaps, 434-435 
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PostScript imagedatato 
portable graymap, 

433-434 

QRT ray tracer output to 
portable pixmaps, 436-437 
raw grayscale bytes to 
portable graymaps, 439 
raw RG B bytes to portable 
pixmaps, 439-440 
ray tracer output to portable 
pixmaps, 333 

SGI imagefilestoportable 
anymaps, 483-484 
Solitaire files to portable 
anymaps, 488-489 
spaces to tabs, 559 
SPOT satellite images to 
portable graymaps, 495 
strings 

ASCII to doublet 
1039-1040 
to long integers 1041 
to unagned long integers 
1041-1042 
wide character to 
multi byte character, 

1061 

Sun icons to portable 
bitmaps, 262 

Sun raster files to portable 
anymaps, 438 
tabs to spaces, 137 
TIFF files to portable 
anymaps, 515-516 
times 

initializing information, 
1058-1060 
to ASCII, 984-986 
to tm structures 1036- 
1037 

T rueVision T arga files to 
portable pixmaps, 515 
Usenet batch files to IN N 
format, 1281-1282 
UsenixFaceSaver files to 
portable graymaps, 147 


Xll orXIO bitmaps to 
portable, 592 
Xll pixmaps to portable 
677 

X11/X10 window dump 
files to portable anymaps, 
722 

Xconfig file format to 
XF86Config, 454 
XIM files to portable 
pixmaps, 654 
XV thumbnail pictures to 
portable pixmaps, 720 
YUV files to portable 
pixmaps, 730-731 
convolution kernels, generat¬ 
ing, 372-373 
cookies, generating, 317 
copying 
ar utility, 7 
as, 9 

byte strings, 900 
files, 80-81 

converting whiles 108-109 
install, 272-273 
MS-DOS to/from UNIX, 
317-318 
UNIX-to-UNIX, 

563-565 

M S-DOS files to U NIX, 

329 

number signs, 907 
strings, 1030-1031 
ipcpyf) function, 
1027-1028 

copysign() function, 907 
cos() function, 907 
cosh() function, 908 
cosines, 907 
cp, 80-81 
cpp, 81-84 
copying, 84 
options, 82-84 
CPU, listing most intensive 
processes, 533-535 
cr (ftp command), 148 
creat, 815-816 


create module, 800-802 
crond"l275 
crontab, 84-85 
crypt function, 908-909 
csplit, 85-86 
ctags, 87-88,135-137 
bugs, 88 

copying, 136-137 
files, 87 

options, 87,136 

ctermid() function, 909 
ctime, 909-910, 984-986 
ctlinnd, 1276-1279 

bugs, 1279 

commands, 1276-1278 

Ctrl+Alt+Del combination, 
setting function, 1279 
Ctrl alt del, 1425 
ctrlaltdel, 1279 
cu, 88-90 
bugs, 90 

commands, 88-89 
options, 89-90 

cuserid() function, 934-935 

bugs, 935 
errors, 934 
files, 935 

cut, 90-91 

cut buffers, copying selections 
into, 598-599 
cvs, 91-106,1116-1120 

commands, 91-104 
add, 96 
admin, 96 
checkout, 96-97 
commit, 96-98 
diff, 98 
export, 98 
history, 99 
import, 100 
log, 100 
rdiff, 101 
releases 101 
remove, 101-102 
rtag, 102 
status 102 
tag, 102-103 
updates 103-104 
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environment variables, 

105-106 

CVSJGNOREREMOTE 
ROOT, 105 
CVSRSH, 106 
CVSJERVER, 106 
CVSEDITOR, 105 
CVSREAD,105 
CVSROOT, 105 
CVSW RAPPERS, 106 
RCSBIN, 105 
files, 104-105,1117-1119 
options, 92-104 

checkout command, 97 
commit command, 97 
history command, 99 
import command, 100 
rdi IT command, 101 
sending problem reports, 

1279- 1281 
filling out reports 

1280-1281 
startup file 93 
support files, 1116-1120 
CVS_ IGNORE_ REMOTE 
ROOT environment 
variable, 105 
CVS RSH environment 
variable, 106 

CVS_SERVER environment 
variable, 106 
cvsbug, 1279-1281 

EM ACS interface 1281 
environment, 1280 
files, 1281 
filling out reports, 

1280- 1281 
options, 1280 

CVSEDITOR environment 
variable, 105 
CVSREAD environment 
variable, 105 
CVSROOT environment 
variable, 105 

CVSWRAPPERS environment 
variable, 106 


cvtbatch, 1281-1282 
C ydades drivers, tuning, 
1282-1284 
cytune, 1282-1284 

bugs, 1283 
options, 1283 


daemons 

buffer-dirty-flush, 744-745 
configurablefinger daemon, 
1106-1109 
configuration file 
1109-1115 
error messages 1108 
features 1107-1108 
SYSLOG mesages 1108 
cron, 1275 

InterNetNews, 1309-1312 
control messages 1310 
condoling, 1276-1279 
kernel log, 1315-1317 
line printer spooler, 
1318-1320 

network routing, 1380-1382 
N FS mount, 1332-1333 
NFS service, 1347 
powerd, 1359-1360 
pppd, 1360-1369 
timeserver, 1407-1408 
UUCP file transfer, 
1415-1417 
DARPA 

FTP server, 1301-1304 
requestssupported, 
1302-1303 

port numbers, converting 
PRC program numbers to, 
1358-1359 

Telnet server, 1406-1407 
TFTP server, 1407 

data buffers, flushing from 
files to disk, 756-757 
data cachet flushing contents, 
746-747 

data segments, changing, 746 


databases 

bibliographic, 219 
fields 219 

inverted indexes 209-210 
saarching, 210,292-293 
filename, updating, 561-562 
files, searching for patterns, 
295 

news overview 
expiring entries 
1293-1294 
format, 1168-1169 
updating, 1353-1354 
ps, updating, 436 
rebuilding for mail aliases 
file 336 

RGB colorname 
uncompiling, 488 
terminal capability, 

1188-1197 

boolean capabilities 1189 
numeric capabilities 

1189- 1190 
dtring capabilities 

1190- 1197 

Usenet, recovering, 1342- 
1344 

date 106-108 

arguments, 106-107 
files, 108 
options, 108 
dates/times 
converting, 79 
to ASCII, 909-911, 
984-986 

to D izordian format, 
1210-1211 
irings to numbers 
989-990 

formatting, strftimet) 
function, 1032-1034 
returning current, 928-929 
setting, 107-108 
showing, 106-107 
dd, 108-109 
ddate, 1210-1211 
DD check routine, 965 
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DD end routine, 965 
D D start routine, 965 
debug (ftp command), 149 
debugfs, 1284-1285 

commands, 1284-1285 
options, 1284 

declare (shell command), 36 
deltimer, 1424 
delete module, 800-802 
delete (ftp command), 148 
deleting 

binary tree items, 1056 
directories, 829-830 
M S-D OS directory trees, 
319 

MS-DOS files, 318-319 

depmod, 109-112 
configuration, 110-111 
files, 111 
strategy, 111 

descriptor tables, size 
(getting), 760-761 
descriptors, testing, 958-959 
/dev directory, 1236 
devices 

bad blocks (searching for), 
1264 

controlling, 774-788 
ioctl callsflist of), 

775-786 

creating, 815-816, 
1321-1324 

describing all, 1120-1121 
disk, ram, 1094-1095 
DOS (tableof), 1152-1158 
Ethernet, boot-time 
parameters, 1223 
floppy disk, 1080-1083 
configuration, 1080-1082 
hard disk, 1083 
line printer (ioctl() calls), 
1090-1091 

Ip, parameters (setting), 
1413-1414 
opening, 815-816 
PUP, tuning parameters, 
1357 


SCSI tape, drivers, 
1096-1100 
setup, 849 
swapping 

enabling/disabling, 1401 
starting/stopping, 866-867 
terminal (list of), 1197 

DEVINFO, 1120-1121 
df, 112-113 

dialup IP connection handler, 
1285-1288 

dialin mode, 1286-1287 
dialout mode, 1287-1288 

dictionaries, compressing/ 
uncompressing, 496 
diff (cvs command), 98 
difftime, 911, 984-986 
dig, 113-117 
bugs, 117 
environment, 117 
files, 117 
options, 114-115 
dip, 1285-1288 

command mode 1285-1286 
dialin mode, 1286-1287 
dialout mode, 1287-1288 
files, 1288 
dir, 303-304 
bugs, 304 
ftp command, 149 
options, 303-304 
directories 
/, 1236 

adding to stack, 40 
alphabetizing entries, 
1012-1013 
/ bin, 1236 
/boot, 1236 

changing, 35-36, 747-748 
closing, 905-906 
creating, 323 
mkdir, 794-795 
mknod, 795-796 
deleting, 829-830 
/dev, 1236 
displaying list of, 36 
/dog, 1236 


/etc, 1236 
/ etc/skel, 1236 
/etc/Xll, 1236 
files (searching for), 137-142 
getting current, 931 
getting entries, 759 
filesystem-independent 
format, 931-932 
hierarchies, creating, 323 
/home 1236 
/ lib, 1236 

listing contents, 303-304 
/ mnt, 1236 
MS-DOS 

changing, 316-317 
diplaying, 319 
opening, opendir, 989 
printing pathnames, 40 
I proc, 1236 
promoting, 39-40 
RCS, creating, 447-449 
reading 
entries 823 
readdirf) function, 
1002-1003 
removing, 462 
root, changing, 750-751, 
1273 

/sbin, 1237 
scanning for matching 
entries, 1012-1013 
stream, resetting, 1011 
/tmp, 1237 

trees, walking through, 930 
/usr, 1237 
/usr/XllR6,1237 
/usr/XHR6/bin, 1237 
/usr/XHR6/lib, 1237 
/usr/XHR6/lib/Xll, 1237 
/usrXHR6/indude/Xll, 
1237 

directory stream, current 
location (returning), 1048 
directory trees 

MS-DOS, deleting, 319 
shadow directories 
(creating), 294 
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dirs (shell command), 36 
disconnect (ftp command), 
149 

D iscordian dates (converting 
to), 1210-1211 
disks 

adding M S-DOS filesystems 
to, 321-322 

devices, ram, 1094-1095 
displaying usag^limits, 437 
floppy 

formatting, 1295-1296 
marking bad blocks 316 
siting parameters 1391 
M S-D OS, mounting, 
326-327 

quotas, manipulating, 
821-822 

SCSI, drivers, 1095-1096 
summarizing free space 
112-113 

summarizing usage, 120-121 
Xdf, 332 

display argument command 
(telnet), 508 

DISTRIBUTION environ¬ 
ment variable, 529 
div() function, 911 
dividing integers, 911 

floating-point remainders, 
913, 923 

returning quotient and 
remainder, 961 

dmesg, 1288-1289 
dn comp, 1008-1011 
dn'expand, 1008-1011 
dnsdomainname, 259-260 
dnsquery, 117-119 
bugs, 119 
diagnostics, 118 
files, 118 
options, 117-118 
documents 

converting, troff to LaTeX, 
1252-1253 

formatting, gtroff, 237-248 


dollar signs ($) 

bash special parameters, 15 
expansion, 19 
ftp command, 148 
domain names 
current host, 119 
displaying, 259-260 
getting/setting, 760 
querying servers, 117-119 
sending query packets to 
servers, 113-117 
servers, resolver routines, 
1008-1011 

domain servers, looking up 
hostnames with, 257-258 
domainname, 119 
domains, nameserver, 
1334-1338 
querying, 1350-1353 
doodle brush files, converting 
to portable bitmaps, 57 
DOS devices, table of, 
1152-1158 
/dos directory, 1236 
drand48() functions, 912 
drawing bitmaps (commands), 
51-53 

drem() function, 913 
drivers 

busmouse, boot-time 
parameters, 1224 
Cyclades, tuning, 

1282-1284 

floppy disk, boot-time 
parameters, 1223-1224 
SCSI disks, 1095-1096 
SCSI tape devices, 
1096-1100 

ioctl() calls 1097-1100 
sound, boot-time param¬ 
eters, 1224 

d split, 119-120 
du, 120-121 
dumpe2fs, 1289 
dumping files, 345-346 
dup, 753-754 


dup2, 753-754 

duplicate executables, finding, 
61 

duplicating strings, 1031 

E 


e-mail 

notification, 48 
sending, 1387-1390 
abases 1390 
e2fsck, 1289-1291 
bugs, 1291 
exit code, 1290 
options, 1290 

echo (shell command), 36-37 
ECHO REQUEST packets, 
sending, 1358 
ecvt() function, 913-914 
Edit menu commands, bitmap 
application, 53-54 
editing bitmaps, 49-51 
editing-mode variable 
(readline), 28 
editors 

emacs, 130-133 
bugs 133 
distributing 133 
files 132-133 
manuals 132 
mouse button bindings 
132 

options 130 
X Window System, 
131-132 

stream-oriented, saesed 
editres, 121-126 

beginning sessions, 121 
blocking requests, 124 
commands, 121-122 
environment, 126 
files, 126 
options, 121 
resource box, 123-124 
resources, 124-125 
widgets, 125-126 
window, 121 
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edquota, 1291-1292 
egrep, 224-226 

bugs, 226 
diagnostics, 226 
options, 224-225 
regular expressions, 225-226 

$else parser directive 
(readline), 29 
elvis, 126-128 

bugs, 128 

environment, 127-128 
files, 127 
options, 127 
ref interaction, 455 
tag files, 135-137 
elvprsv, 128-129 
elvrec, 129-130 
emacs, 130-133 
bugs, 133 
distributing, 133 
files, 132-133 

function key/mouse support, 
134-135 
manuals, 132 

mouse button bindings, 132 
options, 130 
tag files, 135-137 
using emacstool with, 135 
X W indow System, 131-132 
EMACS user interface, 
cvsbug, 1281 
emacstool, 134-135 
bugs, 135 

environment variables, 135 
files, 135 
options, 134 
using with emacs, 135 

enable (shell command), 37 
encoded files, uuencode 
format, 1200 
encryption 

crypt function, 908-909 
memory areas, 980-981 

endgrent() function, 932-933 
$endif parser directive 
(readline), 29 


endmntent() function, 

935- 936 

endnetent subroutine, 

936- 937 

endprotoent() function, 
941-942 

endpwent() function, 943 
endservent() function, 946 
endusershell() function, 
946-947 

endutent() function, 947 
ENV variable (bash), 16 
environ, 1121 
environ command (telnet), 
511 

environment variables 

adding/changing, 996-997, 
1017 

bash, 25-26 
ci, 68 
co, 75 

cvs, 105-106 
CVSIGNORE 
_REMOTE_ROOT, 
105 

CVSRSH, 106 
CVSSERVER, 106 
CVSEDITOR, 105 
CVSREAD,105 
CVSROOT, 105 
CVS// RAPPERS, 106 
RCSBIN, 105 
cvsbug, 1280 
dig, 117 
editres, 126 
elvis, 127-128 
emacstool, 135 
fsinfo, 145 
fslsfonts, 146 
fstobdf, 146 
ftp, 154 
gawk, 172 

getopt() function, 939 
getting, 932 
groff, 229 
gtroff, 248 
gzip, 251 


imak$ 267 
info, 270 
Id, 291 
Ikbib, 293 
locate, 295 

l pq, 299 

l pr, 300 
Iprm, 302 
more, 328 
nslookup, 1353 
res, 443 
rcsclean, 444 
resdiff, 445 
resmerge, 450 
ref, 455 

rlog, 459 
rlogin, 461 
script, 475 
startx, 497 
teal, 506 
telnet, 512 
tin, 528-530 

ADD_ADDRESS, 529 
AUTOSUBSCRIBE, 529 
AUTOUNSUBSCRIBE, 
530 

BUG JDDRESS, 529 
DISTRIBUTION, 529 
MAILER, 529 
NNTPSERVER, 529 
ORGANIZATION, 529 
REPLYT0,529 
TI_ACTIVEFILE, 529 
TI_NOVROOTDIR, 529 
TIN_HOMEDIR, 528 
TIN INDEXDIR, 529 
TIN LIBDIR, 529 
TIN SPOOLDIR, 529 
TINRC, 528 
VISUAL, 529 
tset, 541 
twm, 557 
TZ, 987 
ul, 559 

xauth, 589, 592 
xdipboard, 597 
xdock, 595 
xcmsdb, 593 
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xconsole, 598 
xdm, 608 
XFree86, 637 
xhost, 644 
xinit, 666 
xlogo, 668 
xlsatoms, 669 
xlsclients, 669 
xlsfonts, 671 
xmodmap, 675 
xprop, 680 
xrdb, 684 
xrefresh, 685 
xstdcmap, 700 
xterm, 717 
xwd, 722 
xwininfo, 724 
xwud, 726 
eqn, seegeqn 

equation formatting, 202-206 
erand48() functions, 912 
erf() function, 914 
erfc() function, 914 
errno, 916-917 
error functions, 914 
errors 
access, 741 
adjtimex, 743 
bdflush, 745 
bind, 745-746 
cacheflush, 747 
chdir/fchdir, 747-748 
chmod, 749 
chown, 749-750 
chroot, 750-751 
clone, 751 
close, 752 

codes, describing (returning 
strings), 1032 
creat, 816 
dup/dup2, 753 
execve, 754 
fchmod, 749 
fchown, 749-750 
fcntl, 756 
fdatasync, 757 
fork/vfork, 758 


fsync, 759 

getdents, 759 

getdomainname 760 

getgroups, 762 

gethostname 763 

getitimer, 764 

getpeername 765 

getpriority, 766-767 

getrlimit, 768 

getsid, 768 

getsockname, 769 

getsockopt, 771 

gettimeofday, 773 

idle, 774 

ioctl, 774 

iopl, 789 

kill, 790 

killpg, 791 

link, 791-792 

listen, 792 

llseek, 793 

I seek, 794 

mkdir, 795 

mknod, 796 

mlockall, 798 

mmap, 799 

modifyjdt, 800 

mount, 803 

mprotect, 804 

mremap, 806 

msgctl, 807 

msgget, 808 

msgop, 810 

munlock, 812 

munmap, 799 

mysnc, 811 

nanosleep, 813 

nice 814 

open, 816 

pause, 817 

personality, 818 

return value, 797 

returning number, 916-917 

setdomainname, 760 

setgroups, 762 

sethostname, 763 

setitimer, 764 


setpriority, 766-767 
setrlimit, 768 
setsockopt, 771 
settimeofday, 773 
symbolic error names, 
916-917 
unmount, 803 
escape character, bash, 14 
etags, 135-137 
copying, 136-137 
options, 136 
/etc directory, 1236 
/etc/modules file, 1152 
/etc/skel directory, 1236 
/etc/Xll directory, 1236 
Ethernet devices, boot-time 
parameters, 1223 
Euclidean distance (finding), 
953 

EU ID variable (bash), 15 
eval (shell command), 37 
event timers, managing, 1424 
ex, see elvis 
exclamation points (!) 
bash special parameters, 15 
ftp command, 148 
exec (shell command), 37 
execl function, 914-916 
execle function, 914-916 
execlp function, 914-916 
exect function, 914-916 
executable files, compressing/ 
expanding, 252-253 
executables, duplicate 
(finding), 61 

executing programs, 754-755 
pausing, 813-814 
suspending, 1061 
execv function, 914-916 
execve, 754-755 
execvp function, 914-916 
exit, 739-740,917 
shell command, 37 
xauth, 591 

exit status (commands), 26 
exp() function, 918 
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expand, 137 
expand-tilde variable 
(readline), 28 

expanding files, seecompress- 
ing/expanding files 
expansion, 18-21 

arithmetic, 20 
brace, 19 

command substitution, 20 
history, 33-34 

event desgnators 33 
modifiers 34 
word desgnators 33 
parameter, 19-20 
pathname, 21 
process substitution, 20 
quote removal, 21 
tilde, 19 

word splitting, 21 

expire, 1292-1293 
expire.ctl, 1121-1123 
expireover, 1293-1294 
expml() function, 918 
exponents; 918 
export 

CVS command, 98 
shell command, 37 

exported kernel symbols, 
displaying, 284-285 
exports, 1123-1125 

files, 1124 
options, 1123 
user ID mapping, 
1123-1124 

expressions 

conditional, evaluating, 43 
find, 138 
gawk, 166 
gpic, 213-214 
grep, 225-226 
label, grefer, 223-224 
numeric, gtroff, 239 
regular, sed, 476-477 
ext filesystem, 1125 
ext2 filesystem, 1125 
extracting from archives, 5-7 


F 


fabs() function, 919 
face fi les, converti ng to 
portable bitmaps, 726 
fastrm, 1294-1295 
fc (shell command), 37-38 
FCEDIT variable (bash), 17 
fchdir, 747-748 
fchmod, 748-749 
fchown, 749-750 
fdose function, 919 
fcntl, 755-756 
fcvt() function, 913-914 
fd, 1080-1083 

configuration, 1080-1082 
ioctl() calls supported, 1082 
FD CLR macro, 836 
FD'iSSET macro, 836 
FD SET macro, 836 
FD ZERO macro, 836 
fdatasync, 756-757 
fdformat, 1295-1296 
fdisk, 1296-1297 
fdopen function, 924-925 
feof function, 919-920 
terror function, 919-920 
fflush function, 920-921 
ffs() function, 921 
fg (shell command), 38 
fgetc() function, 945 
fgetgrentf) function, 921-922 
fgetpos function, 927-928 
fgetpwent() function, 

922-923 

fgets() function, 945 
fgrep, 224-226 

bugs, 226 
diagnostics, 226 
options, 224-225 
regular expressions, 225-226 

fields, awk, 163 

FIFOs (named pipes), 1403 

creating, 323-325, 982-983 
system logging, 1403 

FIG NO RE variable (bash), 17 


file descriptors 

duplicating, 23 
manipulating sets, 836 
opening, 23 
reading from, 822 
writing to, 889-890 
File menu commands, bitmap 
application, 53 
file table 

adding entries, 1428-1429 
description, 1425-1426 
initializing, 1427 
moving files to end, 1431 
removing files, 1431-1432 
structure, 1426 
table entries, 1426 
unreferenced entries, 
fetching, 1428 

file-creation mask, setting, 45 
file_ table, 1425-1426 

table entries, 1426 
table structure, 1426 

file table init, 1427 
filechan, 1297-1298 
filename databases, updating, 
561-562 
filenames 
matching, 924 
temporary, creating, 
983-984 

fileno function, 919-920 
files 

aborting transfer, 152 
access permissions, 
changing, 61-62 
agetty, 1261 
Atari 

compressed Spectrum, 
converting to portable 
pixmaps 494 
DegasPIl, converting to 
portable pixmaps 378 
DegasPI3, converting to 
portable bitmaps 379 
uncompressed Spectrum, 
converting to portable 
pixmaps 495-496 
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attributes, 59 

changing (second extended 
filesyiem), 59-60 
authority (X), xauth file 
utility, 587-592 
AutoCAD slide, converting 
to portable pixmaps, 
490-491 
bash, 46 
binary 

encoding/decoding, 

565-566 

locating for commands 
575-576 

Biorad confocal, converting 
to portable graymaps 
48-49 

bitmap, converting, 49 
to portable pixmaps 57 
block special, creating, 325 
character special, creating, 
325 

comparing, 78-79 
compressed 

comparing, 731-732 
searching for regular 
expressions 733 
viewing text, 733-734 
com pressi ng/expandi ng, 
248-252 

concatenation, 251 
executable files 252-253 
computing checksums, 501 
concatenating, 58-59 
configuration values, getting, 
925-926 
copying, 80-81 
between machines 
440-441 

converting while 108-109 
install, 272-273 
counting bytes/word^ lines, 
70, 574 

creating, 815-816 
madcs 880 

cuserid() function, 935 
cutting sections from, 90-91 


cvs, 104-105,1117-1119 
startup, 93 
cvsbug, 1281 
database, searching for 
patterns, 295 
date 108 
descriptors 
dosing, 752 
duplicating, 753-754 
manipulating, 755-756 
domainname, 119 
doodle brush, converting to 
portable bitmaps, 57 
dumping, 345-346 
/etc/modules, 1152 
executing, 914-916 
exports, 1124 

face converting to portable 
bitmaps, 726 
filesystem description, 
accessing, 935-936 
filters, hexdump, 254-256 
FITS, converting to portable 
anymaps, 142-143 
font, 1128 

adding font-metric 
information, 2 
creating, 3 

groff (creating for), 513 
formats, converting Xconfig 
to XF86Config, 454 
free, 144 

gcc/g++, 159-160, 200 
GEM IM G, converting to 
portable bitmaps, 201 
GIF, converting to portable 
anymaps, 208-209 
Gould scanner, converting 
to portable pixmaps, 211 
group, getting entries, 
921-922, 932-934 
group ownership, changing, 
61 

gtroff, 248 

gzip, forcing .gz extension, 
732-733 


H IPS, converting to 
portable graymaps, 256 
FI P PaintJet, converting to 
portable pixmaps, 381 
httpd, 261 

identifying processes, 154- 
155 

identifying RCS keyword 
strings in, 262-263 
ifconfig, 1305 
ILBM, converting to 
portable pixmaps, 263-264 
image converting to 
portable anymap, 4 
imake 266 

I mg-whatnot, converting to 
portable pixmaps, 267 
joining fields, 282-283 
linking, 293-294, 791-792 
Lisp machine bitmap, 
converting to portable 
graymaps, 292 
listing attributes, 304-305 
location, changing, 828-829 
lock, creating for shell 
scripts, 487 
login, 297 

login record, 1198-1200 
M acintosh PICT, convert¬ 
ing to portable pixmaps, 
379-380 

M acPaint, converting to 
portable bitmaps, 309-310 
MAKEDEV, 1321 
makefiles, creating 
dependencies in, 312-314 
man, 1248 

manual page, locating for 
commands, 575-576 
mapping/unmapping, 
799-800 
merging 
lines 347 
three way, 320 
mesg, 321 
modprobe, 111 
mount, 1332 
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MS-DOS 

changing attribute flags 
315-316 

copying to/from U NIX, 
317-318, 329 
deleting, 318-319 
displaying contents 
333-334 

manipulating (mtoolj, 
330-333 
moving, 327 
renaming 329-330 
mtools, testing, 330 
named, 1337 
names 

changing, 828-829 
displaying from U senet 
hi story file 226-227 
naming conventions 153 
.netrc, 153-154 
NLM outfiles, converting 
object code into, 338-339 
nontext, printing strings 
from, 498 

numbering lines, 337-338 
object 

copying/trandating, 

341-342 

discardin g ymbols from, 
499 

displaying information 
from, 342-343 
listing section and total 
szes 489-490 
listing ymbolsfrom, 
339-340 

offsets, repositioning, 
793-794 

opening, 815-816 

advisory locks (applying/ 
removing), 757 
outputting 
ends of, 504 
headers 253-254 
ownership, changing, 62-63, 
749-750 


password, editing, 
1418-1419 

PCX, converting to portable 
pixmaps, 368-369 
permissions 

changing, 748-749 
checking, 741-742 
setting modes 272-273 
Photo-CD, converting to 
portable pixmaps, 260-261 
portable anymap 
format, 1173 
reading, 971 
writing, 971-972 
portable bitmap 
format, 1170-1171 
reading, 968 
writing, 968-969 
portable graymap 
format, 1171-1172 
reading, 970 
writing, 970 
portable pixmap 
format, 1173-1174 
reading, 974 
writing, 974 

PostScript, converting to 
portable anymaps, 434- 
435 

preserving after crashes, 
128-129 

printer/plotter accounting, 
reading, 1354-1355 
printing, in reverse, 503-504 
protocol definition, 1180- 
1181 
RCS 

changing attributes 

441-443 

deaning, 443-445 
comparing revisons 

445- 446 

controlling access 67 
format, 1181-1183 
freezing configuration, 

446- 447 
modes 67 


organization (diagram), 
1182 

printing log mesages 
458-460 

rdtrie/ingre/isions 71-75 
qaedfying, 66-67 
storing revisons 64-69 
temporary files 67 
recovering after crashes, 
129-130 

refs, generating, 87-88 
remote distribution, 

451-454 

removing, 461-462 
columns 77-78 
setsof 1294-1295 
renaming, 334-335 
resolver configuration, 
1183-1184 
reversing lines, 457 
searching for (in directories), 
137-142 

SF86Config, generating, 

633 

SGI image, converting to 
portable anymaps, 

483-484 

shar, unpacking, 560-561 
shrinking, 488 
Solitaire converting to 
portable anymaps, 

488-489 

sorted, removing duplicate 
lines, 560 
source, locating for 
commands, 575-576 
spell-checking utilities, 281 
splitting, 85-86,119-120, 
494-495 

status, getting, 863-864 
string table C sourcefile^ 
headers, 314-315 
substituting definitions into, 
500-501 

suffixes, list of, 1249-1252 
Sun raster, converting to 
portable anymaps, 438 
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swapping 

enabling/disabling, 1401 
iarting/Scopping, 866-867 
symbolic links, 867-869 
synchronizing 

in-coredata, 756-757 
in-corestate, 758-759 
with memory maps 811 
tag 

ariacs 135-137 
vi, 135-137 
tags, generating, 87-88 
temporary 

creating, 983,1053-1054 
naming, 1049,1054 
text 

converting for printing, 
429-430 

creating gcal resource files 
from, 558 
sorting, 492-493 
TIFF, converting to portable 
anymaps, 515-516 
time zone information, 
1197-1198 

timestamps (changing), 536 
transfer parameters, 153 
T rueVision T arga, convert¬ 
ing to portable pixmaps, 
515 

truncating, 879-880 
UNIX 

copying between systems 
563-565 

copying to MS-DOS, 335 
restoring filenames 324- 
325 

U senix FaceSaver, convert¬ 
ing to portable graymaps, 
147 

user group, 1131 
UUCP transfer requests, 
processing, 1415-1417 
uuencode, format, 1200 
XFree86, 638-639, 
1201-1208 
Device section s 
1204-1206 


Filessection, 1201 
Keyboard section, 1202 
M onitor sections 
1203-1204 
Pointer section, 
1202-1203 
Screen sections 
1206-1208 

ServerF lags section, 1201 
XIM , converting to portable 
pixmaps, 654 

YUV, converting to portable 
pixmaps, 730-731 
Z, recompressing to GZ, 
734-735 

Zeiss confocal, converting to 
portable anymaps, 732 
filesystem checks 

group identity (setting), 
843-844 

user identity (setting), 844 
filesystem description file, 
accessing, 935-936 
filesystems, 1125-1126 

buffers, flushing, 1401-1402 
building, 1325-1326 
checking, 1298-1300 
debugger, 1284-1285 
commands 1284-1285 
options 1284 

deleting names from, 1008 
device entries, maintaining, 
1320-1321 

dumping information, 1289 
ext, 1125 
ext2,1125 

hierarchy, description of, 
1236-1238 
FI igh Sierra, 1125 
hpfs, 1125 
iso9660,1125 
MIN IX, 1125 
cons stency checker, 
1300-1301 
creating, 1326-1327 
mounting/dismounting, 
802-804,1328-1332 


msdos, 1125 
names, deleting, 882 
ncpfs, 1126 
nfs, 1125 

export list, 1123-1125 
proc, 1125 
quotas 

summarizing, 1376 
turning on/off, 

1372-1373 
repairing, 1298-1299 
Rock Ridge 1125 
root, mounting, 849 
scanning, 1371-1372 
second extended 
checking, 1289-1291 
creating, 1324-1325 
loi+found directory, 1327 
tunable parameters 
(adjusting), 1412-1413 
setup, 849 
smb, 1126 
static information, 
1126-1127 

statistics, getting, 883-884, 
865-866 
sysv, 1125 
table of, 1427-1428 
type information, getting, 
871 

umsdos, 1125 
vfat, 1125 
xiafs, 1125 

fi lesystems command, 
1427-1428 
filters 

Laplacian relief, running on 
portable pixmaps, 413 
more, 327-328 
commands 328 
environment, 328 
options 327-328 
nonlinear (pnmnlfilt), 
390-391 
nroff output, 77 
reverse line feeds, 76 
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find, 137-142 

actions, 140-142 
expressions, 138 
numeric arguments, 

138-140 
operators, 142 
options, 138 
findaffix, 274, 280 
bugs, 282 
files, 281 
see a/so i spell 

finger daemons, configurable, 
1106-1109 

configuration file, 
1109-1115 
error messages, 1108 
features, 1107-1108 
SYSLOG messages, 1108 
finger information, changing, 
60 

finite!) function, 959 
first in - first out scheduling, 
833-834 

FITS files, converting to 
portable anymaps, 142-143 
fitstopnm, 142-143 
floating-point numbers 

absolute value 919 
converting 

to fractional/integral 
components 927 
to strings 913-914, 
930-931 

extracting integral and 
fractional values, 984 
multiplying, by integral 
powers of 2, 961 

flock, 757 

floorf) function, 923 
floppy disks 

da/ices, 1080-1083 

configuration, 1080-1082 
drivers, boot-time 
parameters, 1223-1224 
formatting, 1295-1296 
marking bad blocks, 316 
parameters, setting, 1391 
fmod() function, 923 


fmt, 143 

fnmatch() function, 924 
fold, 143-144 
font files 

adding font-metric 
information, 2 
creating, 3 

font formats 

converting 

Bitmap D idribution to 
Portable Compiled, 47 
packed format to portable 
bitmaps 381 
PodtScriptPFB format to 
ASCII, 369 
grofffont, 1127-1129 
DESC file 1127-1128 
font servers (X) 

displaying information 
about, 145 

generating BDF fonts, 
146-147 

listing fonts, 145-146 
fonts 
files, 1128 

creating for groff, 513 
grops styles, 231-232 
man pages, 1247 
X 

displaying all characters 
in, 633-636 
tiding, 670-671 
X font server, 641-643, 689 
configuration, 642 
naming, 643 

fopen function, 924-925 

errors, 925 

mode argument sequences, 
924-925 

return values, 925 

fork, 758 

form (ftp command), 149 
formatting 

dates, strftimet) function, 
1032-1034 

documents, gtroff, 237-248 
equations, 202-206 
floppy disks, 1295-1296 


input, 1013-1015 
conversions 1014-1015 
flags 1014 
line lengths, 143 
man pages, 1246-1248 
fonts 1247 
macros 1248 
preamble, 1246-1247 
sections 1247-1248 
output, 992-996, 
1022-1023 

conversion specifiers 994 
examples 995 
flags 993-994 
technical papers 
groff_me macros 
1225-1227 
groff_mm macros 
1227-1234 
groff_ms macros 
1234-1236 

times, strftimef) function, 
1032-1034 
troff tables, 236-237 

fpathconf() function, 
925-926 

fprintf function, 992-996 
fpurge function, 920-921 
fputc() function, 997-999 
fputs() function, 997-999 
fractal forgeries, 404-407 
fread function, 926-927 
free, 144 

free() function, 976 
freopen function, 924-925 
frexp() function, 927 
fscanf function, 1013-1015 
fsck, 1298-1300 
fsck.minix, 1300-1301 
fseek function, 927-928 
fsetpos function, 927-928 
fsinfo, 145 
fslsfonts, 145-146 
fstab, 1126-1127 
fileform at/options, 
1165-1167 
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fstat, 863-864 
fstatfs, 865-866 
fstobdf, 146-147 
fstopgm, 147 
fsync, 758-759 
ftell function, 927-928 
ftime function, 928-929 
ftok function, 929-930 
FTP (FileTransfer 
Protocol), DARPA server, 
1301-1304 
ftp, 147-154 

aborting transfer, 152 
bugs, 154 

commands, 148-152 
i 148 
$, 148 
?, 152 

account, 148 
append, 148 
ascii, 148 
bell, 148 
binary, 148 
bye, 148 
case, 148 
cd, 148 
cdup, 148 
chmod, 148 
close 148 
cr, 148 
debug, 149 
delete 148 
dir, 149 
disconnect, 149 
form, 149 
get, 149 
glob, 149 
hash, 149 
help, 149 
idle 149 
led, 149 
1$ 149 
maedef, 149 
mdelete 149 
mdir, 150 
mget, 150 
mkdir, 150 


mis 150 
mode, 150 
modtime 150 
mput, 150 
newer, 150 
nlii, 150 
nmap, 150 
ntrans 150-151 
open, 151 
prompt, 151 
proxy ftp, 151 
put, 151 
pwd, 151 
quit, 151 
quote, 151 
rear, 151 
regd, 151 
remotehelp, 151 
remoteiatus 151 
rename, 151 
rest, 151 
restart, 151 
rmdir, 152 
runique 152 
send, 152 
sendport, 152 
ste, 152 
sze 152 
iatus 152 
irud, 152 
yiem, 152 
trace, 152 
type 152 
umask, 152 
user, 152 
verbose, 152 

environment variables, 154 
file naming conventions, 
153 

file transfer parameters, 153 
.netrefile 153-154 
options, 147-148 
tenex, sendport, 152 

ftpd, 1301-1304 

bugs, 1303 

FTP requests supported, 
1302-1303 
options, 1302 


(truncate, 879-880 
ftw() function, 930 
full-duplex connections, 
shutting down, 855 
function bindings, displaying, 
35 

functions 

calling at termination, 
897-898, 988 

headers, displaying, 455-456 
library, undocumented, 

1060 

portable pixmap programs, 
973-974 
color names 974 
memory management, 973 
reading files 974 
writing files 974 
fuser, 154-155 
(write function, 926-927 

G 


g++, 155-160,174-201 

bugs, 160 
copying, 160, 201 
filename suffixes, 174-175 
files, 159-160, 200 
options, 155-159,175-178 
assembler, 181 
codegeneration, 198-199 
debugging 186-187 
diredory, 182-183 
language 178-180 
linker, 181-182 
machinedependent, 
191-198 

optimization, 188-190 
preprocessor, 180-181 
targd, 190-191 
warning 183-186 
pragmas, 159, 200 
g3topbm, 160-161 
games, 1210 
gawk, 161-173 
actions, 165-166 
arithmetic functions, 
168-169 
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bugs, 172 

reporting, 172-173 
control statements, 167 
environment variables, 172 
fields, 163 
functions, 170 
GNU extensions, 171 
historical awk features 
supported, 172 
I/O statements, 167 
operators, 166-167 
options, 161-162 
patterns, 165-166 
POSIX compatibility, 171 
printf statement, 167-168 
program execution, 162-163 
regular expressions, 166 
special filenames, 168 
sprintff) function, 167-168 
string constants, 169-170 
string functions, 169 
time functions, 169 
variables, 163-165 
arrays 164 
built-in, 163-164 
typing and converson, 
164-165 

version information, 172 
gcal, 173-174 

running one day ahead, 506 
resource files, creating from 
text files, 558 
gcc, 174-201 

assembling output, 8-9 
bugs, 201 
copying, 201 

filename suffixes, 174-175 
files, 200 
options, 175-178 
assembler, 181 
codegeneration, 198-199 
debugging, 186-187 
directory, 182-183 
language, 178-180 
linker, 181-182 
madhine-dependent, 
191-198 


optimization, 188-190 
preprocessor, 180-181 
target, 190-191 
warning, 183-186 
pragmas, 200 

gcvt() function, 930-931 
GEM IMG files, converting to 
portable bitmaps, 201 
gemtopbm, 201 
GenerateMessagelD routine, 

964 

geqn, 202-206 

automatic spacing, 203 
bugs, 206 

customization, 204-205 
equation components, 
202-203 
files, 206 
fonts, 206 
macros, 206 

new primitives, 203-204 
options, 202 

get (ftp command), 149 
get_current_dir_name() 
function, 931 
getemptyfilp, 1428 
get kernel syms, 800-802 
getc() function, 945 
getchar() function, 945 
GetConfigValue routine, 965 
getcwdf) function, 931 
getdents, 759 
getdirentries function, 

931-932 

getdomainname, 760 
getdtablesize, 760-761 
getegid, 761 
getenv() function, 932 
geteuid, 773 

G etF i I eC onfi gVal ue routi ne, 

965 

GetFQDN routine, 965 
getgid, 761 

getgrent() function, 932-933 
getgrgid() function, 933-934 
getgrnam() function, 933-934 
getgroups, 761-762 


gethostid, 762-763 
gethostname, 763 
getitimer, 763-764 
getlist, 206-207 
getlogin() function, 934-935 
getmntent() function, 

935- 936 

GetM oderatorAddress 
routine, 965 

getnetbyaddr subroutine, 

936- 937 

getnetbyname subroutine, 
936-937 

getnetent subroutine, 936-937 

getopt, 207-208 

getoptf) function, 937-940 

environment variables, 939 
getopt_long() example 
939-940 

return value, 939 

getopt long() function, 
938-940 

getopt long only() function, 
938 " 

getopts (shell command), 38 
getpagesize, 765 
getpass function, 940-941 
getpeername, 765 
getpgid, 845-846 
getpgrp, 845-846 
getpid, 766 
getppid, 766 
getpriority, 766-767 
getprotobyname() function, 
941-942 

getprotobynumber() 
function, 941-942 
getprotoent() function, 
941-942 

getpw() function, 942-943 
getpwent() function, 943 
getpwnam() function, 944 
getpwuid() function, 944 
GetResourceU sage routine, 
965 

getrlimit, 767-768 
getrusage, 767-768 
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gets() function, 945 
getservbyname() function, 
946 

gctservbyport() function, 946 
getserventf) function, 946 
getsid, 768 
getsockname, 769 
getsockopt, 769-772 
bugs, 772 
errors, 771 

options recognized, 770-771 
SO BROADCAST, 771 
SO DEBUG, 770 
SO DONTROUTE, 770 
SO ERROR, 771 
SO JEEP ALIVE, 770 
SOLINGER, 770 
SO RCVBUF, 771 
SO RCVLOWAT, 771 
SO RCVTIM EO, 771 
SO REUSEADDR, 770 
SOSNDBUF, 771 
SO_SNDLOWAT, 771 
SO SNDTIMEO, 771 
SO TYPE, 771 
return value, 771 
GetTimelnfo routine, 965 
gettimeofday, 772-773 
getuid, 773 

getusershell() function, 
946-947 

getutent() function, 947 
getutid() function, 947 
getutlinef) function, 948 
getw function, 948 
getwd() function, 931 
GIF files, converting to 
portable anymaps, 208-209 
giftopnm, 208-209 
giles, gpic, 215 
gindxbib, 209-210 
glob (ftp command), 149 
glob() function, 949-950 
glob dot filenamesvariable 
(bash), 17 

globfree() function, 949-950 


glookbib, 210 
gmtime, 984-986 
gmtime() function, 909-910 
gnroff, 210-211 
GNU linker, 287-291 
copying, 291 
environment, 291 
options, 288-291 
GNU ar, seear 
GNU as, see as 
GNU Bourne-again shell,see 
bash 

Gould scanner files, convert¬ 
ing to portable pixmaps, 211 
gouldtoppm, 211 
gpic, 211-215 

bugs, 215 

commands, 212-213 
expressions, 213-214 
file, 215 
mode 212 
options, 211-212 
versus pic, 212-215 
gprof, 216-217 

graph profile data, displaying, 
216-217 

graphics (ASC11), converting 
to portable graymap, 10 
graphs 

system load average 533 
topological sorts, 542 

grayscale ramps, generating, 
374-375 

greater than signs (>), 
redirection operator, 21 
grefer, 217-224 

bibliographic databases, 219 
bugs, 224 
citations, 219-220 
commands, 220-222 
files, 224 

label expressions, 223-224 
macro interface, 224 
options, 218-219 


grep, 224-226 

bugs, 226 
diagnostics, 226 
options, 224-225 
regular expressions, 225-226 

grodvi, 227-228 
groff, 228-230 

availability, 230 
bugs, 230 

creating font files for, 513 
environment, 229 
files, 229 

guessing options, 230 
interpreting .so requests, 

236 

options, 229 

output, converting to TeX 
dvi format, 227-228 
PostScript driver, 230-235 
preprocessing references, 
217-224 

typewriter device driver, 235 

groff font format, 1127-1129 

DESC file, 1127-1128 

groff me, 1225-1227 
groff mm, 1227-1234 

extensions, 1227-1229 
number variables, 
1233-1234 
strings, 1233 
variables, 1229-1230 
groff ms, 1234-1236 
groffout, 1129-1131 
grog, 230 
grops, 230-235 
files, 234 

font styles, 231-232 
options, 231 
X commands, 232-233 

grotty, 235-236 
group, 1131 

Group 3 fax files, converting 
to portable bitmaps, 

160-161 

group access lists 

getting/setting, 761-762 
initializing, 955 
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group file entries, getting, 
921-922, 932-934 
group identity, setting, 845 
group IDs 

getting/setting, 761, 

845- 846 

real and effective, setting, 

846- 847 

group ownership (files), 
changing, 61 
groups 

adding to system, 

1258-1259 
logging into, 336-337 
process, sending signals to, 
960 

grow_ files, 1428-1429 
grttoppm, 436-437 
gsoelim, 236 
gtbl, 236-237 
gtroff, 237-248 
environment, 248 
escape sequences, 239-240 
files, 248 

fractional point sizes, 238- 
239 

incompatibilities, 247-248 
long names, 238 
numeric expressions, 239 
options, 238 
requests, 241-244 
extended, 244 
number registers 245-246 
warnings, 246-247 
gunzip, 248-249 
see a/sD gzi p 
gzexe, 252-253 
gzip, 248-252 
bugs, 252 

diagnostics, 251-252 
environment, 251 
options, 249-250 

gzip files, forcing .gz exten¬ 
sion, 732-733 


H 


handling signals, 857-858 
hard disks 

boot-time parameters, 
1220-1221 
da/ices, 1083 

partition tables, manipulat¬ 
ing, 1296-1297 

hard drives, partitioning, 
1265-1269 

hard-reset() action (xterm), 
715 

hardware, video (identifying), 
501-503 
hash 

ftp command, 149 
shell command, 38 

hash tables 

creating, 951 
freeing memory, 951 
searching, 951 

hasmntopt() function, 
935-936 

hcreate() function, 951-952 
hd, 1083 

hdestroy() function, 951 
head, 253-254 
H eaderC lean From routine, 
964 

HeaderFind routine, 964 
headers function, displaying, 
455-456 
help 

ftp command, 149 
shell command, 38 
xauth command, 591 
here-documents, 22-23 
hexdump, 254-256 
hier, 1236-1238 

directories, 1236-1238 
/, 1236 
/bin, 1236 
/boot, 1236 
/dev, 1236 
/dos 1236 
/etc, 1236 


/etc/skd, 1236 
/dtc/Xll, 1236 
/home, 1236 
/lib, 1236 
/mnt, 1236 
/proc, 1236 
/±in, 1231 
/tmp, 1237 
/usr, 1237 
Iusr/X11R6,1237 
lusr/XllR6/bin, 1237 
lusrlXllR6IUb, 1237 
lusr/XllR6HiblXll, 1237 
/usrX 11R 6/indude/X 11, 
1237 

hierarchies 

directory (creating), 323 
filesystem, description of, 
1236-1238 

H igh Sierra filesystem, 1125 
HI PS files, converting to 
portable graymaps, 256 
hipstopgm, 256 
histchars variable (bash), 

17-18 

HISTCMD variable (bash), 

16 

HISTFILE variable (bash), 17 
HISTFILESIZE variable 
(bash), 17 
histograms 

drawing for PGM or PPM 
files, 388 

portable pixmaps, printing, 
408 

history, 1131-1132 

control variable (bash), 17 
cvs command, 99 
shell command, 39 

history expansion (bash), 
33-34 

event designators, 33 
modifiers, 34 
word designators, 33 

history lists (bash), 32-33 

displaying, 39 

HISTSIZE variable (bash), 17 
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HOME variable (bash), 16 
/home directory, 1236 
horizontal-scroll-mode 
variable (readline), 28 
host, 257-258 
bugs, 258 
customizing, 258 
options, 257-258 
host byte order, converting 
between network byte order, 
901-902 

host ID s, printing, 258-259 
hostid, 258-259 
hostname, 259-260, 
1238-1239 

hostnamecompletionfile 
variable (bash), 18 
hostnames 

displaying, 259-260 
looking up, 257-258 
resolving, 1238-1239 

hosts 

identifiers, getting/setting, 
762-763 

names, getting/setting, 763 
sending messages to users 
on, 473 

hosts.nntp, 1132-1133 
hosts.nntp.nolimit, 

1132-1133 

hosts_ access, 1133-1136 

access control files, 1133 
access control rules, 1133 
bugs, 1136 
diagnostics, 1136 
files, 1136 
operators, 1134 
patterns, 1133-1134 
remote username lookup, 
1134-1135 

shell commands, 1134 
wildcards, 1134 

hosts access() function, 
950"-951 

hosts ctlf) function, 950-951 
hosts_ options, 1137-1139 

diagnostics, 1139 
options, 1137 


HOSTTYPE variable (bash), 
16 

H P PaintJet files, converting 
to portable pixmaps, 381 
hpcdtoppm, 260-261 
hpfs filesystem, 1125 
hsearch() function, 951-952 
htonlf) function, 901-902 
htons() function, 901-902 
httpd, 261 

hyperbolic cosines, 908 
hyphens (-), bash special 
parameters, 15 
hypot() function, 953 

I 


I/O 

awk statement, 167 
port permissions, setting, 
788 

ports, functions, 816 
privilege level, changing, 
788-789 

standard I/O library, 
1025-1027 

ICC cancel routine, 956 
ICC close routine* 956 
ICC command routine* 956 
1C Copen routine* 956 
ICC pause routine, 956 
ICC reserve routine, 956 
ICCsettimeout routine, 956 
icombine, 274, 281 
files, 281 
see a/so ispell 
icontopbm, 262 
ident, 262-263 
idle* 774 
errors, 774 
ftp command, 149 
return value, 774 
ID s(group), searching for 
matches, 1429 

$if parser directive (readline), 
28-29 

ifconfig, 1304-1305 


IFS variable (bash), 16 
ignore() action (xterm), 713 
IGNOREEOF variable (bash), 
17 

ijoin, 274, 281 

files, 281 
see a/so ispell 

ILBM files, converting to 
portable pixmaps, 263-264 
ilbmtoppm, 263-264 
image files, converting to 
portable anymap, 4 
image parameter, values, 1374 
imake, 264-267 

environment variables, 267 
files, 266 
input, 266 
options, 265 
X Window System, 266 
Imakefiles, creating Makefiles 
from, 672 

Img-whatnot file, converting 
to portable pixmaps, 267 
imgtoppm, 267 
import (cvs command), 100 
in group p, 1429 
inb, 816 " 
inb p, 816 

inbound zone transfers, 
1333-1334 

index() function, 953 
indexes, archives (generating 
for), 437-438 
inet_addr() function, 954 
inet_aton() function, 954 
inet_lnaof() function, 954 
inet makeaddr() function, 
954 

inet_netof() function, 954 
inet_ network!) function, 954 
inet ntoa() function, 954 
inetd, 1305-1307 
inews, 267-269 
infinite results 

returning value for, 954-955 
testing for, 959 
infnan() function, 954-955 
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info, 269-270 

commands, 269-270 
environment, 270 
options, 269 

info command (xauth), 591 
init, 1307-1309 
diagnostics, 1309 
files, 1308 
run levels, 1308 
init module, 800-802 
init~ timer, 1424 
initgroups() function, 955 
initializing 

terminals, 539-542 
X sessions, 496-497 
initstate() function, 
1001-1002 
inittab, 1139-1141 
inittab file, 1398 
ini, 816 
ini p, 816 

inn.conf, 1141-1142 
innconfval, 270-271 
innd, 1309-1312 

control messages, 1310 
header modifications, 1311 
logging, 1311-1312 
protocol differences, 
1310-1311 

inndcomm routines, 956 
inndstart, 1309-1312 
INNVersion routine* 966 
innwatch.ctl, 1142-1144 
innxmit, 1312-1313 
input 

formatting, 1013-1015 
conversions 1014-1015 
flags 1014 
reading, 27-32 

controlling key bindings 
27 

denoting keystrokes 27 
macro definitions 28 
readline commands 
29-32 

redirecting, 22 


input lines, wrapping, 143- 
144 

input, see el vis 

INPUTRC variable (bash), 17 
insb, 816 

insert() action (xterm), 713 
insert-eight-bit() action 
(xterm), 713 
insert-selection() action 
(xterm), 713 
insert-seven-bit() action 
(xterm), 713 
insert file free, 1429 
insl, 816 
insmod, 271-272 
insque() function, 957 
install, 272-273 
installing 

loadable modules, 271-272 
rstartd, 469 
spottopgm, 495 
sysklogd, 1403 

installit, 273-274 
insw, 816 
integers 

absolute values, 892-893 
converting, between host 
and network byte order, 
901-902 
dividing, 911 

floating-point remainders 
913, 923 

returning quotient and 
remainder, 961 
long, labs, 960-961 
rounding, 904 
downward, 923 
to, 1011-1012 
interactive shells, 45 
interfaces 

name daemon control, 
1338-1339 
network 

attaching to serial line 
1399 

configuring, 1304-1305 


serial mouse, 1092-1094 
Microsaft protocol, 1093 
MM protocol, 1094 
M oussSystems protocol, 
1093 

Sun protocol, 1093 

interned atoms, listing, 
668-669 
Internet 

addresses, manipulating, 
953-954 

extended I nternet services 
daemon, 655-664 
inetd superserver, 
1305-1307 

services, listing, 1184-1186 
InterNetNews 

buffered file-writing, 1264- 
1265 

configuration data, 
1141-1142 
daemon, 1309-1312 
control messages 1310 
controlling, 1276-1279 
file-writing, 1297-1298 
InterNetNewslibrary 
dientlib, 904-905 
INND communication 
routi nes, 956 
libinn routines, 962-966 
CAdoss, 964 
CAIiStopen, 964 
CAopen, 964 
CloseOnExec, 965 
DD check, 965 
DD end, 965 
DD start, 965 
GetConfigValue, 965 
GetFileConfic/Value, 965 
GetFQDN, 965 
GetM oderatorAddress 
965 

GetResourceJsage 965 
GdtTimdnfo, 965 
HeaderFind, 964 
INNVersion, 966 


■ I nterNetNews library 


LockFile, 965 
NNTPcheckartidet 965 
NNTPconnect, 965 
NNTPlocalopen, 965 
NNTPremoteopen, 965 
NNTPsendarticle, 966 
NNTPsendpasword, 966 
Radix32, 966 
ReadlnDescriptor, 966 
ReadlnFilet 966 
SetNonBlocking, 965 
Quick I/O, 998 
interrupt key sequence, 
routing, 1425 
interval timers 

getting/setting value, 
763-764 

HIM ER_PROF, 764 
IT IM ER_REAL, 764 
HIM ER_VIRTUAL, 764 
value definitions, 764 

inverse hyperbolic cosines, 
893-894 

inverse hyperbolic sines, 895 
inverse hyperbolic tangents, 
897 

inverted indexes, biblio¬ 
graphic databases, 209-210 
invocation, bash, 45-46 
inw, 816 
inw p, 816 
iocti, 774-788 

arguments, 787-788 
calls 

consoles 1074-1080 
fd de/ice support, 1082 
Hi of, 775-786 
Ip, 1090-1091 
sd, 1095-1096 
i, 1097-1100 
duplicates, 788 
errors, 774 
return value, 774 
ioperm, 788 
iopl, 788-789 
errors, 789 
return value, 789 


IP 

dialup connections, handler, 
1285-1288 

routing table (manipulat¬ 
ing), 1379-1380 
ipc, 789,1144-1146 
message queues, 1145 
resource access permissions, 
1144-1145 

semaphore sets, 1145-1146 
shared memory segments, 
1146 

ipc facilities 

getting information on, 

1314 

removing, 1313-1314 

IPC system calls, 789 
ipcrm, 1313-1314 
ipcrs, 1314 

isalnum() function, 958 
isalpha() function, 958 
isascii() function, 958 
isatty function, 958-959 
isblank() function, 958 
iscntrl() function, 958 
isdigit() function, 958 
isgraph() function, 958 
isinf() function, 959 
islower() function, 958 
isnan() function, 959 
ISO character sets 
2022,1066 
4873,1066 
8859,1064-1065 
8859-1,1239-1242 
alphabets 1240 
characters 1240-1242 
iso9660 filesystem, 1125 
ispell, 274-279,1084-1090 
affix file, 1084-1085 
alternate string characters, 
1087 
bugs, 282 

capitalization rules, 279 
character-set section, 1086 
commands, 274-275 
flags, 1088 


headers, 1085 
options, 275-279 
options statements, 
1085-1086 

prefix/suffix tables, 1088 
root words 
case, 1084 
extending, 1085 
modifying 1088-1089 
isprint() function, 958 
ispunct() function, 958 
isspace() function, 958 
issue, 1146-1147 
isupper() function, 958 
isxdigit() function, 958 
HIMER PROF interval 
timer, 764 

HIMER REAL interval 
timer, 764 

ITIMER VIRTUAL interval 
timer, 764 

J 


j0() function, 959 
jl() function, 959 
jn() function, 959 
job control, 24-25 
jobs, displaying, 39 
jobs (shell command), 39 
join, 282-283 
jrand48() functions, 912 

K 


kbdrate, 1314-1315 
Kerberos authentication, 461 
kernel 

boot-time parameters, 
1216-1224 

A daptec configurations 
1219-1220 

argumentlii, 1216-1217 
Buiogic configuration, 
1220 

busmous drivers 1224 
cards not accepting, 1220 
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CD-ROMs 1222-1223 
debug argument, 1217 
Ethernet de/ices 1223 
floppy did: drivers 
1223-1224 

future domain configura¬ 
tion, 1220 

hard disks 1220-1221 
mem= argument, 1218 
no-hit argument, 1217 
no387 argument, 1217 
Pro Audio configuration, 
1220 

ramdisk= argument, 1218 
reboot=warm argument, 
1218 

ressrve= argument, 

1217- 1218 

ro argument, 1217 
root= argument, 1217 
rw argument, 1217 
SCSI device arguments 

1218- 1219 

SCSI tape configuration, 
1219 

Seagate ST-Ox 
configuration, 1220 
sound drivers 1224 
TrantorT128 
configuration, 1220 
exported symbols, display¬ 
ing, 284-285 
log buffer, 873 
message ring buffer, reading/ 
clearing, 872-874 
modules, loading at boot 
time, 1152 

name getting, 880-881 
ring buffer, controlling, 
1288-1289 

kernel clock, adjusting, 
742-743 

kernel log daemon, 

1315-1317 
kernel logging, 1402 
kernel_mktime 1430 
key bindings, displaying, 35 


key combinations, 
Ctrl+Alt+Del (setting 
function), 1279 
key sequences (interrupt), 
routing, 1425 
keyboard repeat rate 
resetting, 1314-1315 
keymap variable (readline), 28 
keymapf) action (xterm), 713 
keymaps(X), modifying, 
672-676 

keywords, RCS, identifying in 
files, 262-263 
kill, 283-284, 790 

bugs, 790 
errors, 790 
options, 283 
return value, 790 
shell command, 39 
killall, 284 

killing client connections (X 
servers), 666-667 
killpg, 790-791, 960 
klogd, 1315-1317 

files, 1317 
options, 1315 

signal handling, 1316-1317 

kmem, 1091-1092 

KO18-R character set, 1065 

ksyms, 284-285 

L 


labs() function, 960-961 
Laplacian relief filters, 
running on portable 
pixmaps, 413 
last, 285-286 

Latin-1 character set, 1064 
Latin-2 character set, 1064 
Latin-3 character set, 1064 
Latin-4 character set, 1064 
Latin-5 character set, 1065 
Latin-6 character set, 1065 
Ibxproxy, 286-287 

network connections, 286 
options, 286 


led (ftp command), 149 
lcong48() functions; 912 
Id, 287-291 

copying, 291 
environment, 291 
options, 288-291 
ldexp() function, 961 
ldiv() function, 961 
less than signs (<), redirection 
operator, 21 
let (shell command), 39 
letters, converting 

to lowercase, 1055-1056 
to uppercase, 1055-1056 
lfind() function, 975-976 
lgamma() function, 962 
/lib directory, 1236 
libinn routines, 962-966 
CAdose, 964 
CAIistopen, 964 
CAopen, 964 
CloseO nExec, 965 
DD check, 965 
DDend, 965 
DD start, 965 
G etconfigValuev 965 
GetFileConfigValue 965 
GetFQDN, 965 
GetM oderatorAddress, 965 
GetResourceUsage, 965 
GetTimelnfo, 965 
H eaderFind, 964 
INN Version, 966 
LockFile, 965 
N N T Pcheckartide, 965 
N NTPconnect, 965 
N NTPIocalopen, 965 
N NTPremoteopen, 965 
N NTPsendartide, 966 
N N T Psendpassword, 966 
Radix32, 966 
ReadlnDescriptor, 966 
ReadlnFile, 966 
SetN on Blocking, 965 
libpbm routines, 966-969 
constants, 968 
endian i/o, 967 
errors, 967 



■ libpbm routines 


file management, 967 
initialization, 968 
keyword matching, 967 
memory management, 968 
messages, 967 
reading files, 968 
types, 968 

writing files, 968-969 
libpgm routines, 969-970 

constants, 969 
initialization, 969 
memory management, 969 
reading files, 970 
types, 969 
writing files, 970 
libpnm routines, 970-972 
constants, 970 
format promotion, 972 
initialization, 971 
memory management, 971 
reading files, 971 
types, 970 

writing files, 971-972 
XEL manipulation, 972 
XEL manipulations, 971 
libppm, 973-974 
color names, 974 
memory management, 973 
reading files, 974 
writing files, 974 
libraries 

shared, selecting, 883 
standard I/O, 1025-1027 

library functions, undocu¬ 
mented, 1060 
LILO, 1216 

configuration file, 

1147-1151 

global options 1148-1149 
kernel options 1150-1151 
per-image section, 
1149-1150 

line buffered streams, 1016 
line printer 

control program, 1317-1318 
devices, 1090-1091 
ioctlf) calls 1090-1091 
spooler daemon, 1318-1320 


linear searches, arrays, 
975-976 

LINENO variable (bash), 15 
link, 791-792 
linkers, Id (GNU linker), 
287-291 

copying, 291 
environment, 291 
options, 288-291 

linking files, 293-294, 791- 
792 

Lisp Machine bitmap files, 
converting to portable 
graymaps, 292 
lispmtopgm, 292 
list 

bash command, 13 
xauth command, 591 

listen, 792-793 
lists 

bash, 12-13 
columnating, 78 
variable argument (declar¬ 
ing), 1023-1024 

Ikbib, 292-293 
llseek, 793 
In, 293-294 
Indir, 294 
loadable modules 
installing, 271-272 
support, 800-802 
unloading, 462-463 
viewing, 305 
loadlin program, 1216 
local (shell command), 39 
local descriptor table, reading/ 
writing, 800 

local variables, creating, 39 
locale 1243-1244 
setting, 1018-1019 
localeconv, 974-975 
localtime, 909-910,984-986 
locate, 295 

lock files, creating for shell 
scripts, 487 
LockFile routine, 965 


locking memory 
mlock, 796-797 
mlockall, 797-798 

locks (advisory), applying/ 
removing open files, 757 
log (cvs command), 100 
log() function, 918 
Iogl0() function, 918 
loglp() function, 918 
logarithms, 918 
1 plus argument, 918 
base-10, 918 
logger, 295-296 
logging 

innd, 1311-1312 
kernel, 1402 
system, 1402-1404 
configuration file 
1402-1403 
FIFOs 1403 
messages 1404-1405 
remote 1403 
Usenet, log file 
maintenance 1346-1347 
login, 296-297 
login shells, 45 
changing, 63 
exiting, 39 
logins 

changing groups, 336-337 
displaying last, 285-286 
login command, 296-297 
login record files, 

1198-1200 
preventing, 1168 
remote, 460-461 

K erberos authentication, 
461 

root, tty lines (listing), 1184 
shells, pathnames, 1186 

logout (shell command), 39 
logs 

system 

making entries 295-296 
ending messages to, 
1045-1046 
xinetd, 661-663 


memchr() function ■ 


long integers, absolute values, 
960-961 

longjmpf) function, 975 
look, 297-298 
loops 

exiting, 35 
resuming, 36 

lowercase, converting letters 
to, 1055-1056 
Ip, 1090-1091 

Ip devices, setting parameters, 
1413-1414 

l pc, 1317-1318 

commands, 1317-1318 
diagnostics, 1318 

l pd, 1318-1320 

key characters, 1319 
options, 1319 

l pq, 298-299 
bugs, 299 
diagnostics, 299 
environment, 299 
options, 298-299 

l pr, 299-301 
bugs, 301 
diagnostics, 301 
environment, 300 
options, 299-300 

Iprm, 301-302 
bugs, 302 
diagnostics, 302 
environment, 302 
options, 301 
Iptest, 302 

Irand48() functions, 912 

Is, 303-304 

Is (ftp command), 149 

Isattr, 304-305 

lsearch() function, 975-976 

I seek, 793-794 

Ismod, 305 

Istat, 863-864 

lynx, 306-309 

commands, 308-309 
options, 306-308 


M 


macdef (ftp command), 149 
Macintosh PICT files, 
converting to portable 
pixmaps, 379-380 
M acPaint files, converting to 
portable bitmaps, 309-310 
macptopbm, 309-310 
magic cookies, generating, 

317 

mail addressing, 1244-1246 

abbreviations, 1245 
case sensitivity, 1245 
compatibility, 1245 
postmasters, 1246 
routing, 1245 
mail, see e-mail 
MAIL variable (bash), 16 
MAIL WARNING variable 
(bash), 16 

mailaddr, 1244-1246 

abbreviations, 1245 
bugs, 1246 
case sensitivity, 1245 
compatibility, 1245 
postmasters, 1246 
routing, 1245 

MAILC HECK variable (bash), 
16 

MAILER environment 
variable, 529 

MAILPATH variable (bash), 
16 

make, 310-312 

imake preprocessor, 264-267 
options, 311 

makeactive, 1342-1344 
makedepend, 312-314 

algorithm, 313 
bugs, 314 
options, 312-313 

MAKEDEV, 1320-1324 

files, 1321 
options, 1321-1324 

MAKED EV.cfg, 1151 


makefiles 

creating dependencies in, 
312-314 

creating from I makefiles, 
672 

makehistory, 1342-1344 
makestrs, 314-315 

bugs, 315 
directives, 315 
options, 314 
syntax, 314-315 

malloc() function, 976 
man, 1246-1248 
man pages, formatting, 
1246-1248 

fonts, 1247 
macros, 1248 
preamble, 1246-1247 
sections, 1247-1248 

mapping files to memory, 
799-800 

mark-modified-lines variable 
(readline), 28 

mask bitmaps, creating from 
regular, 353-354 
masks, file-creation, 880 

setting, 45 

mattrib, 315-316, 330 
mbadblocks, 316, 330 
mblen, 977 
mbstowcs() function, 

977- 978 

mbtowc() function, 978 
mcd, 316-317, 330 
mcookie, 317 
mcopy, 317-318, 330 
M D 5 message digests, 
generating/checking, 318 
md5sum, 318 
mdel, 318-319, 330 
mdelete (ftp command), 149 
mdeltree, 319 
mdir, 150, 319, 330 
mem, 1091-1092 
memccpy() function, 901, 

978- 979 

memchrf) function, 901, 979 
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memcmp() function, 901, 

979- 980 

memcpy() function, 901, 980 
memfrob() function, 901, 

980- 981 

memmem() function, 901, 
981 

memmove() function, 901, 
981 

memory 

access, controlling, 804-805 
allocating, 894, 976 
displaying amount, 144 
freeing, 976 
kernel, 1091-1092 
locking 

mlock, 796-797 
mlockall, 797-798 
mapping/unmapping files 
to, 799-800 
reallocating, 976 
scanning for characters, 979 
shared 

allocating, 851-853 
controlling, 849-851 
operations, 853-854 
system, 1091-1092 
unlocking 

munlock, 811-812 
munlockall, 812-813 
virtual 

remapping addresses 
805-806 

reports 1417-1418 
virtual console 1101-1102 
memory areas 

comparing, 979-980 
copying, 978-981 
encrypting, 980-981 
filling with constant bytes, 
982 

locating substrings in, 981 

memset() function, 901, 982 
merge, 320 

merge command (xauth), 591 
merging files, three-way, 320 
mesg, 321 


message catalogs 

getting messages from, 
902-903 

opening/closing, 903-904 

message queue identifier, 
retrieving, 807-808 
messages 

control, 1310 

control operations, 806-807 
displaying, 321 
log (RCS files), printing, 
458-460 

message of the day file, 1152 
receiving, from sockets, 
826-828 

sending/receiving, 808-811 
sending 

from sockets 842-843 
to qrstem logger, 
1045-1046 
to users 473, 576-577 
signal, printing, 996 
system console monitoring 
with X, 597-598 
system error, printing, 
990-991 

systems, logging, 1404-1405 
Usenet control, handling, 
1115-1116 

writing to users, 574,1383 

meta characters (bash), 12 
meta-flag variable (readline), 
28 

mformat, 321-322, 330 
bugs 322 
options 321-322 
mget (ftp command), 150 
MGR bitmaps, converting to 
portable bitmaps 322-323 
mgrtopbm, 322-323 
MINIX filesystems 1125 
consistency checker, 
1300-1301 
creating, 1326-1327 
mkdir, 150, 323, 794-795 
bugs 795 
errors 795 


options 323 
return value, 795 

mkdirhier, 323 
mke2fs 1324-1325 
mkfifo, 323-324, 982-983 
errors, 982-983 
options 324 
mkfs, 1325-1327 
mklost+found, 1327 
mkmanifest, 324-325 
mknod, 325, 795-796 
bugs 796 
errors, 796 
options 325 
return value, 796 
mkstemp() function, 983 
mkswap, 1327-1328 
mktemp() function, 983-984 
mktims 910,984-986 
mlabel, 325-326, 330 
mlock, 796-797 
mlockall, 797-798 
mis (ftp command), 150 
mmap, 799-800 
mmd, 326, 330 
mmount, 326-327, 330 
mmove, 327, 330 
/ mnt directory, 1236 
mode (ftp command), 150 
mode command (telnet), 508 
mode parameter, values 1374 
modems, conversational 
exchanges, 1269-1273 
abort strings, 1270-1271 
chat script, 1270 
escape sequences 
1271-1272 
report strings 1271 
termination codes, 1272 
timeout value 1271 
moderators, 1151-1152 
modf() function, 984 
modifyldt, 800 
modprobe, 109-112 
configuration, 110-111 
files, 111 
strategy, 111 


mysnc ■ 


modtime (ftp command), 150 
modules 

kernel, loading at boot time 
1152 
loadable 

support, 800-802 
unloading, 462-463 
viewing, 305 

more, 327-328 
motd, 1152 

mount, 802-804,1328-1332 

bugs, 1332 
errors, 803 
files, 1332 
options, 1329-1331 
return value, 803 
mountd, 1332-1333 
mounting M S-D OS disks, 
326-327 

mouse, 1092-1094 

M icrosoft protocol, 1093 
M M protocol, 1094 
M ouseSystems protocol, 
1093 

Sun protocol, 1093 

mprotect, 804-805 
mput (ftp command), 150 
mrand48() functions, 912 
mrd, 329-330 
mread, 329 
mremap, 805-806 
mren, 329-330 
MS-DOS 
directories 

changng, 316-317 
displaying, 319 
trass deldting, 319 
disks, mounting, 326-327 
files 

changing attribute flags 
315-316 

copying to/from U NIX, 
317-318, 329 
deldting, 318-319 
displaying contents 
333-334 

manipulating (mtoolj, 
330-333 


moving 327 
renaming, 329-330 
filesystems, adding to disks, 
321-322 

floppies, marking bad 
blocks, 316 
subdirectories 
creating 326 
moving, 327 
removing, 329 
renaming, 329-330 
volume labels, creating, 
325-326 

msdos filesystem, 1125 
msgctl, 806-807 
msgget, 807-808 
msgop, 808-811 
msync, 811 
mtest, 330 

mtools, 330-333,1152-1158 

bugs, 333 

case sensitivity of V FAT, 
332 

character translation tables, 
1155-1157 

configuration files, testing, 
330 

default values, 1153 
drive geometry 
configuration, 1154-1155 
exit codes, 333 
general purpose drive 
variables, 1153-1154 
global variables, 1153 
long filenames, 331 
mattrib, 330 
mbadblocks, 330 
mcd, 330 
mcopy, 330 
mdel, 330 
mdir, 330 
mformat, 330 
mlabel, 330 
mmd, 330 
mmount, 330 
mmove 330 
mrd, 330 


mren, 330 
mtest, 330 
mtypei 330 

multiple descriptions, 1155 
name clashes, 332 
open flags, 1155 
parsing order of files, 
1157-1158 

per-drive flags/variables, 
1153 

working directory, 331 
Xdf disks, 332 

M TV ray tracers, converting 
output to portable pixmaps, 
333 

mtvtoppm, 333 
mtype, 330,333-334 
multilanguage support 
(description), 1243-1244 
multibyte characters, 
converting to wide 
characters, 978 
multibyte strings, converting 
to wide character, 977-978 
multiple buffers, reading/ 
writing data, 1003-1004 
multiuser chat program, 
727-730 

Boolean options, 729 
daemons, 727 
escape menu, 728 
readdressing, 729 
runtime options, 728-729 
startup file, 729 
username field, 727 
Xll interface, 730 
munchlist, 274, 279 
bugs, 282 
files, 281 
options, 279-280 
seea/so ispell 
munlock, 811-812 
munlockall, 812-813 
munmap, 799-800 
mv, 334-335 
mwrite, 335 
mysnc, 811 
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N 


named, 1334-1338 

boot file, 1334-1336 
files, 1337 
master file, 1336 
options, 1334 
signals, 1337 
SO A record, 1336-1337 
named pipes, see FIFOs 
named-xfer, 1333-1334 
named.reload, 1338 
named.restart, 1338 
namei, 335-336 
options, 336 
output, 335 
names 
bash, 12 

peer, getting, 765 
socket, getting, 769 
nameserver (Internet 
domains), 1334-1338 

boot file, 1334-1336 
control interface, 1338-1339 
master file, 1336 
querying, 1350-1353 
signals, 1337 
SO A record, 1336-1337 
stopping/restarting, 1338 
synchronizing database 
1338 
naming 

font servers, 643 
temporary files, 1049,1054 
xhost, 644 

NaN (not-a-number) results 
returning value for, 954-955 
testing for, 959 

nanosleep, 813-814 
ncpfs filesystem, 1126 
ndc, 1338-1339 
Netnews reader, see tin 
.netrc file, 153-154 
netstat, 1339-1342 
files, 1341 

routing information, 1341 
socket information, 
1340-1341 


network byte order, convert¬ 
ing between host byte order, 
901-902 

network entries, getting, 
936-937 
networking 

displaying active 
connections, 1339-1342 
routing information, 1341 
socket information, 
1340-1341 
interfaces 

attaching to serial line 
1399 

configuring, 1304-1305 
routing daemon, 1380-1382 

newaliases, 336 
newer (ftp command), 150 
newgrp, 336-337 
news 

N etna/vs, see tin 
news software information 
newsgroups, 530 
overview database 
expiring entries 
1293-1294 
format, 1168-1169 
updating, 1353-1354 
receiving from UUCP 
connections, 463-464 
news.daily, 1344-1346 
keywords, 1344-1345 
newsfeeds, 1158-1163 
Distribution headers, 1159 
entries, 1158-1159 
examples, 1162-1163 
feed types, 1161-1162 
flags, 1159-1161 
M E entry, 1161 
newsgroups 

news software information, 
530 

Usenet, listing active, 1104- 
1105 

newslog, 1163-1165, 
1346-1347 

files, 1164 
keywords, 1346 
message action fields, 


1163-1164 

newsrequeue, 1342-1344 
NFS 

mount daemon, 1332-1333 
servers, authentication/print 
request, 1355-1357 
service daemon, 1347 

nfs, 1165-1167 
nfs filesystem, 1125 
export list, 1123-1125 
NFS servers, mount 
information, 1396 
nfsd, 1347 
nice* 814 

nl, 337-338 

nlist (ftp command), 150 
NLM outfiles, converting 
object code into, 338-339 
nlmconv, 338-339 

nm, 339-340 

nmap (ftp command), 150 
nnrp.access, 1167-1168 
nnrpd, 1347-1349 
NNTP 

news, host list, 1132-1133 
servers, 1347-1349 

getting lisb from, 206-207 
passwords 1170 
rdrie/ing U send: articles 
from, 340-341 
sites, access control, 
1167-1168 

N NTPcheckartideroutine, 
965 

N NTPconnect routine, 965 
nntpget, 340-341 
N NTPIocalopen routine, 965 
N N T P remoteo pen routi ne, 

965 

nntpsend, 1349-1350 
nntpsend.ctl, 1168 
NNTPsendartide routine, 966 
NNTPsendpassword routine, 

966 

NNTPSERVER environment 
variable, 529 
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noexitonfailedexec 
variable (bash), 18 
noclobber variable (bash), 18 
nolinks variable (bash), 18 
nologin, 1168 
none, 881 

none (undocumented library 
functions), 1060 
not-a-number (NaN) results 
returning value for, 954-955 
testing for, 959 
notify variable (bash), 17 
nrand48() functions, 912 
nroff 

emulating, 210-211 
output, filtering, 77 
nslookup, 1350-1353 
arguments, 1350 
commands, 1351-1353 
diagnostics, 1353 
environment, 1353 
files, 1353 

ntohl() function, 901-902 
ntohs() function, 901-902 
ntrans (ftp command), 
150-151 
null, 1094 
numbers 
floating-point 
absolute value 919 
converting to fractional/ 
integral components, 

927 

converting to irings 
913-914, 930-931 
pseudo-random, generating, 
912-913 

random, generating, 
1001-1002 
rounding, 1011-1012 
signs, copying, 907 
square roots, 1023 
numeric expressions, gtroff, 
239 


0 


objcopy, 341-342 
objdump, 342-343 
object files 

copying/translating, 

341- 342 

discarding symbols from, 

499 

displaying information from, 

342- 343 

listing section and total sizes, 
489-490 

listing symbols from, 
339-340 

odock, 344 
od, 345-346 

offline printing, 299-301 
oldfstat, 814 
oldlstat, 814 
oldolduname, 814 
OLD PWD variable (bash), 15 
oldstat, 814 
olduname, 814 
on_exit() function, 988 
open, 815-816 
bugs, 816 
errors, 816 
flags, 815 
ftp command, 151 
modes, 815 
return value, 816 
open host command (telnet), 
508 

opendir, 989 
openlog() function, 
1045-1046 

facility argument, 1046 
option argument, 1046 
operators 
awk, 166-167 
find, 142 
redirection, 21 

OPTARG variable (bash), 16 
OPTERR variable (bash), 17 
OPTIND variable (bash), 16 


ORGANIZATION environ¬ 
ment variable, 529 
OSTYPE variable (bash), 16 
outb, 816 
outb p, 816 
outl,~816 
outlp, 816 
output 

formatting, 992-996, 
1022-1023 

conversion specifiers 994 
examples 995 
flags 993-994 
redirecting, 22 

output-meta variable 
(readline), 28 
outsb, 816 
outsl, 816 
outsw, 816 
outw,816 
outw p, 816 
overchan, 1353-1354 
overview.fmt, 1168-1169 
ownership (file), changing, 
62-63, 749-750 

P 


pac, 1354-1355 
packed format fonts, convert¬ 
ing to portable bitmaps, 381 
packets 

ECHO_REQUEST, 
sending, 1358 
route, printing, 1409-1412 

page size, system (getting), 
765 
paging 

disabling, 796-797 
calling process 797-798 
reenabling, 811-813 
papers, formatting 
groff_me macros, 

1225-1227 
groff_mm macros, 
1227-1234 
groff_ms macros, 

1234-1236 
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paragraphs, formatting line 
length, 143 

parameter command substitu¬ 
tion (bash), 20 
parameter expansion (bash), 
19-20 
parameters 
bash, 14-15 
positional, 14 
special, 14-15 
boot-time (kernel), 

1216-1224 

Adaptec configurations 
1219-1220 

argument list, 1216-1217 
Bui ogic configuration, 
1220 

busmouse drivers 1224 
cards not accepting, 1220 
CD-ROMs 1222-1223 
debug argument, 1217 
Ethernet devices 1223 
floppy dil drives 
1223-1224 
future domain 
configuration, 1220 
hard disks 1220-1221 
mem= argument, 1218 
no-hlt argument, 1217 
no387 argument, 1217 
Pro Audio configuration, 
1220 

ramdisk= argument, 1218 
reboot=warm argument, 
1218 

reserve= argument, 

1217- 1218 

ro argument, 1217 
root= argument, 1217 
rw argument, 1217 
SCSI device arguments 

1218- 1219 

SCSI tape configuration, 
1219 

Seagate ST-Ox 
configuration, 1220 


aaund drivers 1224 
TrantorT128 
configuration, 1220 
floppy disk, setting, 1391 
positional 
parang, 38 
renaming, 42 
serial ports, 1392-1394 
parsedate, 989-990 
parser directives, readline, 
28-29 
$else, 29 
$endif, 29 
$if, 28-29 
parsing 

command options, 207-208 
command-line options, 
937-940 

positional parameters, 38 

partition tables, manipulat¬ 
ing, 1296-1297 
DOS 6.x, 1296-1297 
partitioning disk drives, 
1265-1269 

passwd, 346-347,1169-1170 

bugs, 347 
files, 347 

passwd.nntp, 1170 
password files, editing, 
1418-1419 
passwords 

changing, 346-347 
encryption, 908-909 
file entries, writing, 997 
getting, 940-941 
getting file entry, 943-944 
password file 1169-1170 
reconstructing line entry, 
942-943 
paste, 347 

PATH variable (bash), 16 
pathconf() function, 925-926 

options returned, 926 
return value, 926 

pathname expansion (bash), 
21 


pathnames 

canonicalized absolute, 
1004-1005 

following to terminal point, 
335-336 

matching, 924, 949-950 

patterns 

printing lines matching, 
224-226 

search i ng database fi les for, 
295 

pause, 817 

pausing execution, 813-814 
pbm, 1170-1171 
PBM images, displaying on 
4425 terminals, 357 
pbmdean, 348 
pbmfilters, 348-352 
pbmlife 352-353 
pbmmake, 353 
pbmmask, 353-354 
PBM Plus package, programs, 
348-352 
pbmpscale, 354 
pbmreduce, 355 
pbmtext, 355-356 
pbmtolOx, 356 
pbmto4425, 357 
pbmtoascii, 357 
pbmtoatk, 358 
pbmtobg, 358 
pbmtocmuwm, 358-359 
pbmtoepsi, 359 
pbmtoepson, 359 
pbmtog3, 360 
pbmtogem, 360 
pbmtogo, 360-361 
pbmtoicon, 361 
pbmtolj, 361-362 
pbmtoln03,362 
pbmtolps, 362 
pbmtomacp, 363 
pbmtomgr, 363 
pbmtopgm, 364 
pbmtopi3, 364 
pbmtopk, 364-365 
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pbmtoplot, 365-366 
pbmtoptx, 366 
pbmtoxlObm, 366 
pbmtoxbm, 367 
pbmtoybm, 367 
pbmtozinc, 367-368 
pbmupc, 368 
pdose(), 991-992 
pcnfsd, 1355-1357 

authentication, 1355-1356 
file, 1357 
printing, 1356 
reconfiguration, 1357 
PCX files, converting to 
portable pixmaps, 368-369 
pcxtoppm, 368-369 
peers, getting names, 765 
permissions 
file 

changing, 748-749 
siting, 272-273 
port input/output, setting, 
788 

perror, 990-991 
personality, 817-818 
pfbtops, 369 
pgm, 1171-1172 
pgmbentley, 369 
pgmcrater, 370-371 
pgmedge, 371 
pgmenhance, 371-372 
pgmhist, 372 
pgmkernel, 372-373 
pgmnoise, 373 
pgmnorm, 373-374 
pgmoil, 374 
pgmramp, 374-375 
pgmtexture, 375-376 
pgmtofs, 376 
pgmtolispm, 376-377 
pgmtopbm, 377 
pgmtoppm, 378 
Photo-C D files, converting to 
portable pixmaps, 260-261 
phys, 818 

physical addresses, accessing, 
818 


pi3topbm, 379 

pic, versus gpic, 212-215 

commands, 212-213 
expressions, 213-214 
mods 212 

picttoppm, 379-380 

bugs, 379 

fontdirfileformat, 380 

ping, 1358 
pipe, 818-819 
pipelines (|), bash, 12 
pipes, creating, 818-819 
pjtoppm, 381 
pktopbm, 381 
PLIP devices, tuning 
parameters, 1357 
plipconfig, 1357 
pnm, 1173 
pnmalias, 381-382 
pnmarith, 382-383 
pnmcat, 383 
pnmcomp, 383-384 
pnmconvol, 384 
pnmcrop, 385 
pnmcut, 385 
pnmdepth, 385-386 
pnmenlarge, 386 
pnmfile, 386-387 
pnmflip, 387 
pnmgamma, 387 
pnmhistmap, 388 
pnmindex, 388-389 
pnminvert, 389 
pnmmargin, 389-390 
pnmnlfilt, 390-391 

alpha-trimmed mean filter, 
390 

bugs, 391 

combining modes, 391 
edge enhancement, 391 
optimal estimation 
smoothing, 390 

pnmnoraw, 391-392 
pnmpad, 392 
pnmpaste, 392-393 
pnmrotate, 393 


pnmscale^ 393-394 
pnmshear, 394-395 
pnmsmooth, 395 
pnmtile* 395 
pnmtoddif, 396 
pnmtofits, 396-397 
pnmtoiff, 399-400 
pnmtopsi 397 
pnmtorast, 398 
pnmtosgi, 398-399 
pnmtosir, 399 
pnmtoxwd, 400 
popd (shell command), 39-40 
popen() function, 991-992 
popup-menu() action 
(xterm), 713 
port, 1091-1092 
portable anymaps 
antialiasing, 381-382 
bordering, 389-392 
changing maxval, 385-386 
compositing, 383-384 
concatenating, 383 
converting 

to DDIF format, 396 
to FITS format, 396-397 
to PostScript, 397 
to red/blue 3D glasass 
400-401 
to SGI image file 
398-399 

to Solitaire format, 399 
to Sun raster files 398 
to TIFF files 399, 400 
toXll window dumps 
400 

convolving, 384 
creating index of, 388, 389 
cropping, 385 

cutting rectangles from, 385 
describing, 386, 387 
drawing histograms from, 
388 

enlarging, 386 
fileformat, 1173 
flipping, 387 
gamma correction, 387 
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inverting, 389 

pasting rectangles into, 392, 
393 

performing arithmetic on, 
382, 383 

plain format, 391, 392 
programs 
constants 970 
format promotion, 972 
fundionssupporting, 970, 
971, 972 
initialization, 971 
memory management, 971 
reading Hies 971 
types 970 

writing files 971, 972 
XEL manipulations 
971-972 

replicating into specified 
size, 395 
rotating, 393 
scaling, 393, 394 
shearing, 394, 395 
smoothing, 395 
portable bitmaps 

applying Rules of Life to, 
352, 353 
converting 

to Andrew Tool kit raster 
objects 358 
to ASCII graphics 357 
to Atari DegasP 13 files 
364 

to Bennet Yee"face" files 
367 

to BitGraph graphics 358 
toCMU window manager 
bitmaps 358-359 
to compressed G raphO n 
graphics 360-361 
to DEC LN03+Sixd 
output, 362 

to encapsulated PostScript- 
style bitmaps 359 
to Epson printer graphics 
359 


to GEM IMG files 360 
to Gemini 1 Ox graphics 
356 

to Group 3 fax files 360 
to HP LaserJet format, 
361-362 

to M acPaint files 363 
to MGR bitmap, 363 
to packed format fonts 

364- 365 

to portable graymaps 364 
to PostScript, 362 
to Printronix printer 
graphics 366 
to Sun icons 361 
to UN IX plot files 

365- 366 

toXlO bitmaps 366 
toXll bitmaps 367 
to Zinc bitmaps 367-368 
creating with specified size; 
353 

enlarging, 354 
file format, 1170-1171 
flipping pixelsin, 348 
programs 
contents 968 
endian Ho, 967 
errors 967 

file management, 967 
fundionssupporting, 
966-969 

initialization, 968 
keyword matching, 967 
memory management, 968 
messages 967 
reading files 968 
types 968 

writing files 968-969 
reducing, 355 
portable graymaps 
Bentleyizing, 369 
calculating textural features 
on, 375-376 
combining three into a 
portable pixmap, 457-458 


converting 

to L isp machine format, 
376-377 

to portable bitmaps 377 
to portable pixmaps 378 
to U senix FaceSaver 
format, 376 

creatingfrom white noises 

373 

enhancing edges, 371-372 
fileformat, 1171-1172 
mimicking cratered terrain, 
370-371 

normalizing contrast, 
373-374 

outlining edges, 371 
performing oil transfers on, 

374 

printing histogram of values, 
372 

programs 
constants 969 
fundionssupporting, 
969-970 

initialization, 969 
memory management, 969 
reading files 970 
types 969 
writing files 970 
portable pixmaps 

blending together, 408-409 
brightening, 404 
changing pixel color, 
401-402 

changing saturation and 
value, 401 
converting 

to Abekas YU V files 428 
to Atari Degas PI 1 files 
422 

to AutoCAD, 414-416 
to BMP files 416 
to DEC sixel format, 
425-426 

to GIF files 416-417 
to HP PaintJet files 423 
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to HP PaintJet XL PCL 
files, 424 

tolLBM files 418-419 
to M adntosh PICT files 
422-423 

to M itsubishi S340-10 
files 420-421 
toMotifUIL icon files 
427 

to NCSA ICR format, 
417-418 
to PCX files 421 
to portable graymaps 
421-422 

to three portable graymaps 

425 

to three raw YUV files 
428-429 

to T ru&/ision T arga files 

426 

toXll pixmaps 427-428 
toXll puzzle files 
424-425 
creating, 408 
patterns 410-411 
specifying color, 408 
creating from three portable 
graymaps, 457-458 
dimming 
to black, 402 
every other row, 409-410 
displacing pixels, 414 
dithering, 403 
extracting color from, 
419-420 

file format, 1173-1174 
files 

reading, 974 
writing, 974 

fractal forgeries, 404-407 
grayscale assignments 
(performing), 402-403 
histograms (printing), 408 
Laplacian relief filters 
(running on), 413 
normalizing contrast, 409 


programs, functions 
supporting, 973-974 
quantizing colors, 411 
8-planequantization, 
412-413 
multi pie files 412 
shifting lines, 413-414 
portmap, 1358-1359 
ports 

input/output functions, 816 
input/output permissions, 
setting, 788 
serial 

configuring, 1394-1395 
parameters 1392-1394 
ssttintfgetting informa¬ 
tion, 1391-1395 
system, 1091-1092 
positional parameters 
bash, 14 
parsing, 38 
renaming, 42 
POSIX 

gawk compatibility, 171 
regex functions, 1005-1007 
compiling, 1005-1006 
error reporting, 1006 
matching, 1006 
pattern buffer freeing 
1007 

signal set operations, 
1019-1020 

PostScript 

bounding box, extracting, 
433 

files, converting to portable 
anymaps, 434-435 
fonts 

translating from PFB 
format to ASCII, 369 
translating fromPFB 
format to ASCII, 369 
image data, converting into 
portable graymap, 

433-434 
pound sign (#) 
bash comments, 14 
bash special parameters, 15 


pow() function, 918 
powerd, 1359-1360 
powers (rai sing numbers to), 
918 

PPID variable (bash), 15 
ppm, 1173-1174 
ppm3d, 400-401 
ppm brighten, 401 
ppmchange, 401-402 
ppmdim, 402 
ppmdist, 402-403 
ppmdither, 403 
ppmflash, 404 
ppmforge, 404-407 
bugs, 407 
options, 405-407 
ppmhist, 408 
ppmmake, 408 
ppmmix, 408-409 
ppmnorm, 409 
ppmntsc, 409-410 
ppmpat, 410-411 
ppmquant, 411-412 
ppmquantall,412 
ppmqvga, 412-413 
ppmrelief, 413 
ppmshift, 413-414 
ppmspread, 414 
ppmtoacad, 414-416 
ppmtobmp, 416 
ppmtogif, 416-417 
ppmtoicr, 417-418 
ppmtoilbm, 418-419 
ppmtomap, 419-420 
ppmtomitsu, 420-421 
ppmtopcx, 421 
ppmtopgm, 421-422 
ppmtopil, 422 
ppmtopict, 422-423 
ppmtopj, 423 
ppmtopjxl, 424 
ppmtopuzz, 424-425 
ppmtorgb3,425 
ppmtosixel, 425-426 
ppmtotga, 426 
ppmtouil, 427 
ppmtoxpm, 427-428 
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ppmtoyuv, 428 
ppmtoyuvsplit, 428-429 
PPP 

daemon, 1360-1369 
statistics, printing, 
1369-1370 

pppd, 1360-1369 

authentication, 1366-1367 
diagnostics, 1368 
examples, 1367-1368 
files, 1366-1369 
options, 1360-1366 
routing, 1367 
signals, 1369 
pppstats, 1369-1370 
pr, 429-430 
preprocessor, 81-84 
preprocessors, imake, 264-267 
printf function, 992-996 
bugs, 995-996 
printf statement, awk, 

167-168 
printing 
aliases, 35 

application resources, 5 
banners, 1210 
converting text files for, 
429-430 

files, in reverse 503-504 
histograms of portable 
pixmaps, 408 
host IDs, 258-259 
lines matching a pattern, 
224-226 

log messages (RCS files), 
458-460 

machine architecture 8 
offline, 299-301 
packet route, 1409-1412 
pcnfsd, 1356 
PPP statistics, 1369-1370 
printer/plotter accounting 
files (reading), 1354-1355 
removing jobs from queue 
301-302 

ripple test pattern, 302 
signal messages, 996 


spool queue examination, 
298-299 

system activity summary, 
573 

system error messages, 

990- 991 

time zones, 1419 
user/system times, 43 
see a/so line printer 

priority values, getting range, 
830-831 
privileges 

I/O, changing level, 

788-789 

setuid (RCSfiles), 67-68 

/ proc, 1174-1180,1236 

bugs, 1180 

hierarchy outline, 1174- 
1180 

proc filesystem, 1125 
proc_sel, 1430-1431 
process control, initialization, 
1307-1309,1397-1399 
process groups, sending 
signalsto, 790-791,960 
process substitution (bash), 

20 

processes 

0, making idle 774 
accounting, switching on/ 
off, 742 

child, creating, 751, 758 
closing, pdosef) function, 

991- 992 

displaying tree of, 435-436 
execution, suspending, 1061 
execution domain, setting, 
817-818 

group identity, setting, 845 
group ID s 

getting/setting 845-846 
real and effective (acting), 
846-847 
groups 

access lists (getting/setting), 
761-762 

IDs(getting), 761 


identifying, 154-155 
IDs, getting, 766 
listing most C PU -intensive 
533-535 

opening, popen() function, 
991-992 

parents, IDs (getting), 766 
priorities, altering, 
1375-1376 

priority, changing, 814 
reporting status, 430-433 
SCH ED_RR interval, 
getting, 831 
scheduling priorities, 
getting/setting, 766-767 
selecting, by criteria, 
1430-1431 

sending signals to, 790 
raise function, 1000 
starting, on consoles, 1066 
terminating, 283-284, 
739-740 
byname 284 
times, getting, 878-879 
tracing, 820 
user IDs 
getting 773 

real and effective(sstting), 
847-848 
setting, 848-849 
waiting for termination, 
886-889 

yielding processor, 835 

processor, time used (deter¬ 
mining), 905 
profil, 819 
profiling, 819 
programs 

executing, 754-755 
portable anymap 
constants 970 
format promotion, 972 
fundtionssupporting, 
970-972 

initialization, 971 
memory management, 971 
reading files 971 
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types, 970 

writing files 971-972 
XEL manipulations 
971-972 

portable bitmap, functions 
supporting, 966-969 
portable graymap 
constants 969 
fundionssupporting, 
969-970 

initialization, 969 
memory management, 969 
reading files 970 
types 969 
writing files 970 
recompiling, make utility, 
310-312 

running, in new session, 
1395 

terminating 

abortf) fundion, 892 
assertf) fundion, 

895-896 

exit() fundion, 917 

promoting directories, 39-40 
prompt (ftp command), 151 
PROM PT COM MAND 
variable (bash), 17 
prompting (bash), 26 
properties, consoles, 1067 
protocols 

protocols definition file, 
1180-1181 

RPC, rpcgen compiler, 
464-466 

Telnet, interface, 507-512 
XIE, testing, 645-654 

proxy ftp (ftp command), 151 
proxy servers, LBX, 286-287 
PRT ray tracers, converting 
output to portable pixmaps, 
333 

prunehistory, 1370-1371 
ps, 430-433 

bugs, 433 

field descriptions, 432 
options, 430-431 


sort keys, 431-432 
updating, 432, 436 

PS1 variable (bash), 16 
PS2 variable (bash), 16 
PS3 variable (bash), 17 
PS4 variable (bash), 17 
psbb, 433 

pseudo-filesystems, /proc, 
1174-1180 

bugs, 1180 
hierarchy outline, 
1174-1180 

pseudo-random numbers, 
generating, 912-913 
psidtopgm, 433-434 
pstopnm, 434-435 
pstree, 435-436 
psupdate, 436 
ptrace, 820 

pushd (shell command), 40 
put (ftp command), 151 
putfilejast, 1431 
putc() function, 997-999 
putchar() function, 997-999 
putenv, 996-997 
errors, 996 

putpwent() function, 997 

errors, 997 

puts() function, 997-999 
pututline() function, 948 
putw function, 948 
pwd (ftp command), 151 
pwd (shell command), 40 
PWD variable (bash), 15 

Q 


qio, 998 

QRT ray tracer, converting 
output to portable pixmaps, 
436-437 
qsort, 1000 

quantizing colors (pixmaps), 
411 

8-plane quantization, 
412-413 

multiple files, 412 


question marks (?) 

bash special parameters, 15 
ftp command, 152 

queues, inserting/removing 
items, 957 
quit command 

ftp command, 151 
telnet, 508 
xauth, 591 

quit() action (xterm), 714 
quota, 437 

quotacheck, 1371-1372 
quotactl, 821-822 
quotaoff, 1372-1373 
quotaon, 1372-1373 
quotas 

disk, manipulating, 821-822 
remote machines, 1012 

quote (ftp command), 151 
quoting (bash), 14 

R 


Radix32 routine, 966 
raise function, 1000 
ram, 1094-1095 
rand() function, 1001 
random numbers, generating, 
1001-1002 

RANDOM variable (bash), 15 
random() function, 
1001-1002 

randomizing strings, 1032 
ranlib, 437-438 
rarp, 1373 

RARP table, manipulating, 
1373 

rasttopnm, 438 
raw grayscale bytes, convert¬ 
ing to portable graymaps, 
439 

raw RGB bytes, converting to 
portable pixmaps, 439-440 
rawtopgm, 439 
rawtoppm, 439-440 
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ray tracers 

converting output to 
portable pixmaps, 333 
QRT, converting output to 
portable pixmaps, 436-437 

rep, 440-441 
RCS (Revision Control 
System), 447-449 

automatic identification, 

449 

commands, 447-449 
directories, creating, 

447-449 

files 

chang ng attributes 
441-443 

cleaning, 443-445 
comparing revisions 

445- 446 

freezing configuration, 

446- 447 
functions, 447 
revisions, merging, 449-451 

res, 441-443 
bugs, 443 
compatibility, 443 
diagnostics, 443 
environment, 443 
files, 443 
options, 441-443 
RCS files 

controlling access, 67 
format, 1181-1183 
modes, 67 

organization (diagram), 

1182 

printing log messages, 
458-460 

retrieving revisions, 71-75 
specifying, 66-67 
storing revisions, 64-69 
setuid privileges 67-68 
temporary files, 67 
RCS keyword strings, 
identifying, 262-263 
RCSBIN environment 
variable, 105 


rcsclean, 443-445 
resdiff, 445-446 
resfile, 1181-1183 

organization (diagram), 
1182 

resfreeze, 446-447 
rcsintro, 447-449 

automatic identification, 
449 

RCS functions, 447 

resmerge, 449-451 
rdev, 1373-1375 
rdiff (evs command), 101 
rdist, 451-454 
bugs, 454 
diagnostics, 454 
files, 453 
options, 451-452 
re comp function, 1005 
reexec function, 1005 
read (shell command), 40 
read(), file descriptors, 822 
readd ir, 823 
readdir() calls, setting 
position, 1015-1016 
readdir() function, 
1002-1003 

R ead I n D escri ptor routi ne, 
966 

ReadlnFile routine, 966 
readline library, 27-32 

commands, 29-32 
controlling key bindings, 27 
customizing, 27 
denoting keystrokes, 27 
macro definitions, 28 
parser directives, 28-29 
$e(sj 29 
$endif, 29 
$if, 28-29 
variables, 28 
bell-style 28 
comment-begin, 28 
completion-query-items 
28 

convert-meta, 28 
editing-mode 28 
expand-tilde 28 


horizontal-scroll-mode 28 
keymap, 28 

mark-modified-line% 28 
meta-flag, 28 
output-meta, 28 
diow-all-if-ambiguous 28 

readlink, 823-824 
readonly (shell command), 40 
readv, 824-825 
readv() function, 1003-1004 
realloc() function, 976-977 
realpath, 1004-1005 
reboot, 825-826 
recompiling programs, make 
utility, 310-312 
recompressing Z files, 

734-735 
reconfig, 454 
reev, 151, 826-828 
recvfrom, 826-828 
recvmsg, 826-828 
redirection, 21-23 

duplicating file descriptors, 
23 

here-documents, 22-23 
input, 22 

opening file descriptors, 23 
operators, 21 
output, 22 

redraw() action (xterm), 714 
ref, 455-456 

elvis interaction, 455 
environment, 455 
files, 455 
options, 455 
search method, 455 
refreshing screen (X), 684-685 
refs files, generating, 87-88 
regcomp function, 1005-1007 
regerror function, 1005-1007 
reget (ftp command), 151 
regex functions, 1005 
POSIX, 1005-1007 
compiling, 1005-1006 
error reporting, 1006 
matching, 1006 
pattern buffer freeing, 
1007 
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regexec function, 1005-1007 
regfree function, 1005-1007 
regular expressions 

grep, 225-226 
sed, 476-477 

release (cvs command), 101 
remote execution server, 

1376- 1377 

remote file copying, 440-441 
remote logging, 1403 
remote login server, 

1377- 1378 

remote logins, 460-461 

Kerberos authentication, 

461 

remote machines, starting X 
programs on, 676 
remote quota server, 1384 
remote shell, 466-467 
remote shell server, 

1385-1386 

Remote Start client, see rstart 
Remote Start rsh helper, see 
rstartd 

remote status, displaying, 472 
remote systems, command 
execution, 569-571 
remote user communication 
server, 1405-1406 
remotehelp (ftp command), 
151 

remotestatus (ftp command), 
151 

remove, 1008 

cvs command, 101-102 
xauth command, 591 

remove, file_ free, 1431-1432 
remque() function, 957 
rename, 828-829 
rename (ftp command), 151 
renice, 1375-1376 
REPLY variable (bash), 15 
REPLYTO environment 
variable, 529 
repquota, 1376 
res init, 1008-1011 


res_mkquery, 1008-1011 
res_query, 1008-1011 
res search, 1008-1011 
res] send, 1008-1011 
reserved words (bash), 12 
reset, 456, 539-542 
compatibility, 542 
options, 540 

setting environment, 540 
terminal type mapping, 
540-541 

reset (ftp command), 151 
resize, 456-457 
resolver, 1183-1184 
resolver routines, 1008-1011 
resolving hostnames, 
1238-1239 

resource editor, see editres 
resources 

limits, getting/setting, 
767-768 

usage, getting, 767-768 

restart (ftp command), 151 
return (shell command), 40 
return value* errors, 797 
rev, 457 

reverse line feeds, filtering, 76 
Revision Control System, see 
RCS 

rewind function, 927-928 
rewinddir() function, 1011 
rexecd, 1376-1377 
bugs, 1377 
diagnostics, 1377 
protocol, 1376-1377 
RGB colornamedatabases, 
uncompiling, 488 
rgb3toppm, 457-458 
rindex() function, 953 
rint() function, 1011-1012 
ripple test pattern (printing), 
302 

rlog, 458-460 
rlogin, 460-461 
rlogind, 1377-1378 
rm, 461-462 


rmdir, 462, 829-830 

bugs, 830 
errors, 829 
options, 462 

rmdir (ftp command), 152 
rmmod, 462-463 
rnews, 463-464 
Rock Ridge filesystem, 1125 
root logins, tty lines (listing), 
1184 

root directories 

changing, 750-751,1273 

root filesystem, mounting, 
849 

root window (X), setting 
parameters, 693-694 
round-robin scheduling, 834 
rounding integers, 904 
rounding numbers, 
1011-1012 
route, 1379-1380 
routed, 1380-1382 
bugs, 1382 
files, 1382 

gateways, 1381-1382 
options, 1381 
request packets, 1381 
response packets, 1381 
starting, 1380 
routines 

ICCcancel, 956 
ICCdose, 956 
ICCcommand, 956 
ICCgo, 956 
ICCopen, 956 
ICC pause 956 
ICC reserve 956 
ICCsettimeout, 956 
libinn library, 962-966 
CAdos, 964 
CAIistopen, 964 
CAopei, 964 
CloseOnExec, 965 
DD check, 965 
DD end, 965 
DD start, 965 
GdtConfigValue 965 
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GetFileConfigValue, 965 
GetFQDN, 965 
GetM oderatorAddress 
965 

GetResourceUsagz 965 
GetTimeinfo, 965 
H eaderFind, 964 
INNVersion, 966 
LockFile, 965 
NNTPcheckartidet 965 
NNTPconnect, 965 
NNTPIocalopen, 965 
NNTPremoteopen, 965 
NNTPsendarticle, 966 
NNTPsendpasword, 966 
Radix32, 966 
ReadlnDescriptor, 966 
ReadlnFile 966 
SAN onBlocking, 965 
libpbm, 966-969 
constants 968 
endian Ho, 967 
errors 967 

file management, 967 
initialization, 968 
keyword matching, 967 
memory management, 968 
messages 967 
reading files 968 
types 968 

writing files 968-969 
libpgm, 969-970 
constants 969 
initialization, 969 
memory management, 969 
reading files 970 
types 969 
writing files 970 
libpnm, 970-972 
constants 970 
format promotion, 972 
initialization, 971 
memory management, 971 
reading files 971 
types 970 

writing files 971-972 
XEL manipulation, 972 
XEL manipulations 971 


routing, pppd, 1367 
RPC 

program numbers, 
converting to DARPA port 
numbers, 1358-1359 
protocol compiler, see rpcgen 
services, reporting informa¬ 
tion, 1383-1384 
rpc.rquotad, 1384 
rpc.ru sersd, 1382-1383 
rpc.rwalld, 1383 
rpcgen, 464-466 
options, 465-466 
preprocessor symbols, 465 
rpcinfo, 1383-1384 
rquota() protocol, 1012 
rquotad, 1384 
rsh, 466-467 
rshd, 1385-1386 
rstart, 467-468 
rstartd, 468-471 
configuring, 469 
keywords 470 
installing, 469 
options, 469 

rtag (cvs command), 102 

runique (ftp command), 152 

rup, 472 

rusers, 472-473 

rwall, 473 

rwho, 474 

rwhod, 1386-1387 

S 


saving stack context, 1018 
/sbin directory, 1237 
sbrk, 746 

scandir() function, 
1012-1013 

scanf functions, 1013-1015 

bugs, 1015 

conversions, 1014-1015 
flags, 1014 
return values, 1015 

sched get priority max, 
830-83l" 


sched get priority min, 
830-831" 

sched getparam, 832 
sched getscheduler, 833-835 

errors, 834 
policies, 833 

SCHEDJIFO, 833-834 
SCHEDOTHER, 834 
SCHED_RR, 834 
response time, 834 

schedrrgetinterval, 831 
sched setparam, 832 
schedsetscheduler, 833-835 

errors, 834 
policies, 833 

SCHEDJIFO, 833-834 
SCHED OTHER, 834 
SCHED JR, 834 
response time, 834 

sched_ yield, 835 
scheduling 

algorithm, getting/setting, 
833-835 

parameters, getting/setting, 
832 

policies, 833 
first in - first out, 

833-834 
round-robin, 834 
timediaring, 834 
priorities 

getting/setting 766-767 
value ranges 830-831 
yielding processor, 835 

screen, clearing, 70-71 
screen savers, beforelight, 
47-48 

script, 474-475 
scripts, chat, 1270 
scroll-back() action (xterm), 
714 

scroll-forw() action (xterm), 
714 

SCSI drivers 

diskdrives, 1095-1096 
tape devices, 1096-1100 

sd, 1095-1096 
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searching 

binary trees, 1056 
strings, for character sets, 
1035-1039 

second extended filesystems 
creating, 1324-1325 
lost+found directory, 1327 
tunable parameters 
(adjusting), 1412-1413 
SECONDS variable (bash), 15 
secure() action (xterm), 713 
securetty, 1184 
security 

sysklogd, 1403-1404 
X server, 688-689 
xterm, 712 
sed, 475-480 
addresses, 476 
bugs, 480 

commands, 478-479 
grouping, 478 
9/ntax, 476 
comments, 477 
diagnostics, 479-480 
options, 475 

regular expressions, 476-477 
replacement pattern 
symbols, 477 
search pattern symbols, 
476-477 

seed48() functions, 912 
seekdir() function, 

1015-1016 
select, 835-837 
select-cursor-end action 
(xterm), 714 

seiect-cursor-start() action 
(xterm), 714 

select-end() action (xterm), 
714 

select-extend() action 
(xterm), 714 

select-start() action (xterm), 
714 

selections, copying into cut 
buffers, 598-599 


semaphore sets 

control operations, 837-839 
GET ALL, 838 
GETNCNT, 838 
GETPID, 838 
GETVAL, 838 
GETZCNT, 838 
IPCRMID, 838 
I PC SET, 838 
IPCSTAT, 837 
SET ALL, 838 
SETVAL, 838 
identifiers (getting), 
839-840 

operations, 840-842 

semctl, 837-839 

errors, 838-839 
operations, 837-838 
GET ALL, 838 
GETNCNT, 838 
GETPID, 838 
GETVAL, 838 
GETZCNT, 838 
IPC RMID, 838 
IPC SET, 838 
IPC STAT, 837 
SET ALL, 838 
SETVAL, 838 
semget, 839-840 
semop, 840-842 
send, 842-843 
ftp command, 152 
send arguments command 
(telnet), 508-509 
send-signal() action (xterm), 
714 

sendmail, 1387-1390 

aliases, 1390 
exit status codes, 1390 
files, 1390 
flags, 1388 
options, 1389-1390 
sendmsg, 842-843 
sendport (ftp command), 152 
sendto, 842-843 
serial lines 

monitoring, 1359-1360 
network interfaces, 
attaching, 1399-1401 


serial mouse interface, 
1092-1094 

M icrosoft protocol, 1093 
M M protocol, 1094 
M ouseSystems protocol, 
1093 

Sun protocol, 1093 

serial ports 

configuring, 1394-1395 
parameters, 1392-1394 
setting/getting information, 
1391-1395 

serial terminal lines, 1101 
servers 

biff, 1274-1275 
controlling with xdm, 
612-613 

DARPAFTP, 1301-1304 
requests supported, 
1302-1303 

DARPA Telnet protocol, 
1406-1407 
DARPA TFTP, 1407 
domain 

looking up hostnames 
with, 257-258 
resolver routines 
1008-1011 
font (X) 

displaying information 
about, 145 
generating BDF fonts 
146-147 

listing fonts 145-146 
interned atoms, listing, 
668-669 

Internet, xinetd (starting 
with), 655-664 
Internet domain nameserver, 
1334-1338 
boot file 1334-1336 
control interface 
1338-1339 
master file 1336 
querying, 1350-1353 
s'gnals 1337 
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SOA record, 1336-1337 
iopping/reiarting, 1338 
ynchronizing database, 
1338 

I nternet superserver, 
1305-1307 

LBX proxy server, 286-287 
logged-in users, 1382-1383 
news, sending Usenet 
articles to, 267-269 
NFS 

authentication/print 
request, 1355-1357 
mount information, 1396 
NNTP, 1347-1349 

getting liis from, 206-207 
passwords 1170 
retrieving U ssnet artides 
from, 340-341 
portmap, 1358-1359 
remote execution, 

1376-1377 

remote login, 1377-1378 
remote quota, 1384 
remote shell, 1385-1386 
remote user communication, 
1405-1406 

specifying, xdm, 607-608 
system status, 1386-1387 
message format, 
1386-1387 
X W indow System 
access control program, 
643-645 

display server, 685-690 
file utility, 587-592 
font server, 641-643 
information utility, 614 
killing dients 666-667 
starting, 664-666 
virtual framebuffer, 
717-718 
Xll 

performance comparison 
program, 585-586 
performance test program, 
577-585 


XF86 8514, 615 
XF86_Accel, 614-623 
configuration, 615-616 
files, 622 
options 616 
setup, 616-622 
XF86_AGX, 615 
XF86_Mach32, 615 
XF86_Mach64, 615 
XF86_Mach8, 615 
XF86_M ono, 624-627 
configuration, 624 
files 626 
9dtup, 624-626 
X F86 P9000, 615 
X F86 S3, 615 
XF86_SVGA, 627-631 
configuration, 627-628 
files 630-631 
options 628 
setup, 628-630 
XF86_VGA16, 631-633 
configuration, 631 
files 633 
options 632 
setup, 632 
XF86 W32, 615 
XFree86, 636-641 
configuration, 636 
environment variables 
637 

files 638-639 
key combinations 638 
ndtwork connections 
636-637 
options 637-638 
9iup, 638 

services, 1184-1186 

bugs, 1186 
files, 1186 

Internet, listing, 1184-1186 
N FS, daemon, 1347 
RPC, reporting information, 
1383-1384 

Session Manager Proxy, see 
sm proxy 


sessions 

creating, setsid, 848 
IDs, getting, 768 
typescripts, creating, 

474-475 

X Session M anager, 694-698 
default startup applica¬ 
tions 695 
options 695-698 
proxy, 698 

remote applications 698 
Session menu, 695-696 
SM SAVE DIR 
environment variable 
695 

starting, 695 
tester, 698-699 
.xsssson file 695 
xdm, 600 

sessreg, 480-481 
set 

shell command, 40-42 
telnet command, 509-510 

set-allowl32() action (xterm), 
715 

set-altscreen() action (xterm), 
715 

set-appcursor() action 
(xterm), 715 
set-appkeypad() action 
(xterm), 715 

set-autolinefeed() action 
(xterm), 715 
set-autowrap() action 
(xterm), 715 
set-cursesemul() action 
(xterm), 715 
set-jumpscroll() action 
(xterm), 715 
set-marginbell() action 
(xterm), 715 

set-reverse-video() action 
(xterm), 715 
set-reversewrap() action 
(xterm), 715 

set-scroll-on-key() action 
(xterm), 715 
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set-scroll-on-tty-output() 
action (xterm), 715 
set-scrollbar() action (xterm), 
715 

set-tek-text() action (xterm), 
715 

set-terminal-type() action 
(xterm), 715 

set-visibility() action (xterm), 
715 

set-visual-bell() action 
(xterm), 715 

set-vt-font() action (xterm), 
714 

setbuf function, 1016-1017 
setbuffer function, 1016-1017 
setdomainname, 760 
setegid, 846-847 
setenv() function, 1017 
seteuid, 847-848 
setfdprm, 1391 
setfsgid, 843-844 
setfsuid, 844 
setgid, 845 

setgrent() function, 932-933 
setgroups, 761-762 
sethostid, 762-763 
sethostname, 763 
setitimer, 763-764 
bugs, 764 

defining values, 764 
errors, 764 
return value, 764 
timer types, 764 

setjmp() function, 1018 
setlinebuf function, 
1016-1017 
setlocale() function, 
1018-1019 

setmntent() function, 
935-936 

SetN on Blocking routine, 965 
setpgid, 845-846 
setpgrp, 845-846 
setpriority, 766-767 
setprotoent() function, 
941-942 


setpwent() function, 943 
setregid, 846-847 
setreuid, 847-848 
setrlimit, 767-768 
setserial, 1391-1395 
configuration consider¬ 
ations, 1394-1395 
files, 1395 
options, 1392 
parameters, 1392-1394 
setservent() function, 946 
setsid, 848,1395 
errors, 848 
setsockopt, 769-772 
bugs, 772 
errors, 771 

options recognized, 770-771 
SO-BROADCAST, 111 
SO_DEBUG, 770 
SO_DONTROUTE, 770 
SO_ERROR, 771 
SO JEEPALIVE, 770 
SO-LINGER, 770 
SO-RCVBUF, 771 
SO RCVLOWAT, 771 
SO RCVTIM EO, 771 
SO REUSEADDR, 770 
SO_SNDBUF, 771 
SO_SNDLOWAT, 771 
SO_SNDTIMEO,771 
SO_TYPE, 771 
return value, 771 
setstate() function, 

1001-1002 
setterm, 482-483 
settimeofday, 772-773 
setuid, 848-849 
setup, 849 

setusershell() function, 
946-947 

setutent() function, 947 
setvbuf function, 1016-1017 
SGI image files, converting to 
portable anymaps, 483-484 
sgitopnm, 483-484 
sh, expansion, 19 


shadow directories (creating), 
294 

shar, 484-487 

files, unpacking, 560-561 
options, 484-486 
shared libraries, selecting, 883 
shared memory 
allocating, 851-853 
controlling, 849-851 
commands 850 
ystem calls 851 
operations, 853-854 
shell variables (bash), 15-18 
allow-nullglobexpansion, 
17 

auto_ resume 18 
BASH,15 

BASH _VE RSI ON, 15 
cdable_vars, 18 
CDPATH, 16 
command_oriented_history, 

17 

EN V,16 
EUID,15 
FCEDIT, 17 
FIGNORE, 17 
gl ob_ d ot_ f i I en am es, 17 
histchars, 17-18 
H I ST C M D, 16 
H I ST FILE, 17 
HISTFILESIZE, 17 
history control, 17 
HIST SIZE, 17 
HOME,16 

hostname_completion_file 

18 

HOSTTYPE, 16 
IFS, 16 

IGN O REEO F, 17 
IN PUTRC, 17 
LINENO, 15 
MAIL, 16 

MAIL_WARNING, 16 
MAILCHECK, 16 
M AILPATH, 16 
no_exit_on_failed_exec, 18 
noclobber, 18 
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nolinks, 18 
notify, 17 
OLDPWD, 15 
OPTARG, 16 
OPTERR, 17 
OPTIND, 16 
OSTYPE, 16 
PATH, 16 
PPID, 15 

PRO M PT_CO M M AN D, 
17 

PS1,16 
PS2,16 
PS3,17 
PS4,17 
PWD, 15 
RANDOM,15 
REPLY, 15 
SECONDS, 15 
SH LVL, 15 
TM OUT, 17 
UID, 15 
shells 

archives, creating, 484-487 
Bourne-again, 11-46 
aliases 23-24 
arguments 11 
arithmetic evaluation, 34 
blanks 12 
bugs 46 

command ececution, 25 
comments 14 
compound commands 13 
control operators 12 
environments 25-26 
escape character, 14 
exit status 26 
expansion, 18-21 
files 46 
functions 23 
history list, 32-33 
invocation, 45-46 
job control, 24-25 
lists 12-13 
meta characters 12 
names 12 
options 11 


parameters 14-15 
pipelines (\), 12 
prompting, 26 
quoting, 14 
readline 27-32 
redirection, 21-23 
reserved words 12 
hdl variables 15-18 
sgnals 25 

ample commands 12 
words 12 

built-in commands, 35-45 
alias 35 
bg,35 
bind, 35 
break, 35 
builtin, 35 
cd, 35-36 
command, 36 
continue 36 
declare, 36 
dirs 36 
echo, 36-37 
enabling/disabling, 37 
eval, 37 
exec, 37 
exit, 37 
export, 37 
fc, 37-38 
fg, 38 
getopts 38 
hash, 38 
help, 38 
history, 39 
jobs 39 
kill, 39 
let, 39 
local, 39 
logout, 39 
popd, 39-40 
pushd, 40 
pwd, 40 
read, 40 
readonly, 40 
return, 40 
set, 40-42 
shift, 42 


suyend, 42-43 
test expr, 43 
times 43 
trap, 43-44 
type, 44 
ulimit, 44-45 
umask, 45 
unalias 45 
unset, 45 
wait, 45 

commands, executing, 1047 
exiting, 37 
interactive, 45 
login, 45 
changing, 63 
exiting 39 
pathnames 1186 
remote, 466-467 
serve-, 1385-1386 
suspending execution, 42-43 
user, getting, 946-947 
shells file^ 1186 
shift (shell command), 42 
shlock, 487 

SH LVL variable (bash), 15 
shmctl, 849-851 
commands, 850 
errors, 851 
system calls 851 
shmget, 851-853 
bugs, 853 
errors, 852 
system calls 852 
shmop, 853-854 
show-all-if-ambiguous 
variable (readline), 28 
showmount, 1396 
showrgb, 488 
shrinkfile, 488 
shutdown, 855,1396-1397 
bugs 1397 
errors, 855 
files, 1397 
options 1397 
sigaction, 855-857 
sigaddset, 1019-1020 
sigblock, 858 
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sigdel set, 1019-1020 
sigemptyset, 1019-1020 
sigfillset, 1019-1020 
siggetmask, 858 
siginterrupt() function, 1019 
sigismember, 1019-1020 
sigmask, 858 

signal, 857-858,1248-1249 

bugs, 1249 

signal messages, printing, 

996 

signals 

available (list of), 1248-1249 

bash, 25 

blocked 

changng Hi of, 856 
rdeaang, 858-859 
changing process action, 
855-856 

describing with strings 1038 
handling, 857-858 
interrupting system calls 
1019 
masks 

manipulating, 858 
replaang, 856 
pending, examining, 856 
POSIX signal set operations, 
1019-1020 

sending to processes, raise 
function, 1000 
waiting for, 817 

signatures tin, 528 
sigpause, 858-859 
sigpending, 855-857 
sigprocmask, 855-857 
sigreturn, 859 
sigsetmask, 858 
sigsuspend, 855-857 
sigvec, 860 

simple commands (bash), 12 
simpleinit, 1397-1399 

bugs, 1399 
files, 1398 

sin() function, 1020-1021 
sinh() function, 1021 
sirtopnm, 488-489 


site (ftp command), 152 
size, 489-490 
copying, 489-490 
ftp command, 152 
options, 489 
si attach, 1399 
sic command (telnet), 510 
sldtoppm, 490-491 
sleep() function, 1021 
sliplogin, 1399-1401 
diagnostics 1400 
/etc/sl i p.hosts format, 1400 
example, 1400 
parameters, 1400 
smb filesystem, 1126 
smproxy, 491-492 
snprintf function, 992-996 
SOCK DGRAM sockets, 
860-861 

SOCK RAW sockets, 861 
SOCK RDM sockets, 861 
SOCK'SEQPACKET sockets, 
860-861 

SOCK STREAM sockets 
860-861 
socket, 860-861 

errors, 861 
socket types, 860 
SOCKDGRAM, 
860-861 

SOCKRAW, 861 
SOCK RDM, 861 
SO CKSEQ PACKET, 
860-861 

SOCKSTREAM, 
860-861 
socketcall, 862 
socketpair, 862-863 
sockets 
connections 

accepting, 740-741 
initiating, 752-753 
listening for, 792-793 
creating, 860-861 
names 

binding, 745-746 
getting, 769 


options 770-771 

getting/siting, 769-772 
SO BROAD CAST, 771 
SO DEBUG, 770 
SO_DONTROUTE, 770 
SO ERROR, 771 
SO JEEP ALIVE, 770 
SO LINGER, 770 
SO RCVBUF, 771 
SO RCVLOWAT, 771 
SORCVTIM EO, 771 
SO_REUSEADDR,770 
SOSNDBUF, 771 
SO_SNDLOWAT, 771 
SOSNDTIMEO, 771 
SO TYPE, 771 
pairs, creating, 862-863 
peers, getting names, 765 
receiving messages from, 
826-828 

sending messages from, 
842-843 
system calls 862 
types, 860 

SOCKDGRAM, 
860-861 

SOCK JAW, 861 
SOCK RDM, 861 
SOCKSEQPACKET, 
860-861 

SOCK STREAM, 
860-861 

soft-reset() action (xterm), 
715 

Solitaire files, converting to 
portable anymaps, 488-489 
sort, 492-493 
sorted arrays searching, 
900-901 

sorted files removing 
duplicate lines, 560 
sorted word lists, compress¬ 
ing/uncompressing, 496 
sorting arrays, 1000 
sound drivers, boot-time 
parameters 1224 
source command (xauth), 591 
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spaces, converting to tabs, 559 

spctoppm, 494 

special parameters, bash, 

14-15 

! (exclamation points), 15 

# (pound signs), 15 
$ (dollar signs), 15 

* (asterisks), 15 
- (hyphens), 15 

? (question marks), 15 
@ (at signs), 15 
_ (underscores), 15 
0,15 

spell-checking, 274, 280 

buildhash, 279 
findaffix, 280 
icombine 281 
ijoin, 281 
ispell, 274-279 
ispell dictionaries, 

1084-1090 
affix file 1084-1085 
alternate string characters 
1087 

character-set section, 1086 
flags 1088 
headers 1085 
optionsstatements 
1085-1086 

prefix/suffix tables 1088 
root words 1084-1085 
munchlist, 279-280 
tryaffix, 281 

split, 494-495 

splitting files, 85-86,119-120 
spool queue 

examining, 298-299 
removing jobs from, 

301-302 

SPOT satellite images, 
converting to portable 
graymaps, 495 
spottopgm, 495 
sprintf function, 992-996 
sprintf() function, awk, 
167-168 

sputoppm, 495-496 


sq, 496 

sqrt() function, 1023 
square roots (returning), 1023 
srand() function, 1001 
srand48() functions, 912 
srandomf) function, 
1001-1002 

sscanf function, 1013-1015 
st, 1096-1100 

ioctl() calls, 1097-1100 
return values, 1100 

stack, saving context, 1018 
standard colormap utility (X), 
699-700 

standard error output, 
redirecting, 22 
standard output, redirecting, 
22 

start-cursor-extend() action 
(xterm), 714 

start-extend() action (xterm), 
714 

startup time 

adjusting to GM T, 1424- 
1425 

converting, 1430 

startx, 496-497 
stat, 863-864 
statements, awk, 167-168 
states (system), updating, 
1414-1415 
statfs, 865-866 
status 
CVS, 102 
ftp, 152 

telnet command, 512 

stdarg, 1023-1024 
stdio library, 1025-1027 

bugs, 1026 

functions, 1026-1027 

stime, 866 

stpcpy() function, 1027-1028 
strcasecmp(), 1028 
strcat() function, 1028-1029 
strchr() function, 1029 
strcmp() function, 1029-1030 
strcoll() function, 1030 
strcpy() function, 1030-1031 


strcspn() function, 

1038-1039 

strdup() function, 1031 
stream-oriented editor, see sed 
streams 

binary, input/output 
(getting), 926-927 
block buffered, 1016 
buffering operations, 
1016-1017 

checking/resetting status, 
919-920 
closing, 919 
directory 

current location (return¬ 
ing), 1048 
resetting, 1011 
flushing, 920-921 
line buffered, 1016 
opening, 924-925 
repositioning, 927-928 
unbuffered, 1016 
strerror() function, 1032 
strfry(), 1032 
strftime() function, 
1032-1034 

conversion specifiers, 1033 
tm structure members, 1034 

string constants, awk, 

169-170 

string functions, awk, 169 
string variables, configura¬ 
tion-dependent, 906-907 
string!) action (xterm), 714 
strings, 498 
byte 

copying, 900 
operations 901 
writing zeros to, 902 
comparing, 1029-1030 
byte 899-900 
ignoring case, 1028 
using current locale 1030 
concatenating, 1028-1029 
converting 
to doubles 898, 
1039-1040 
to integers 898-899 
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to long integers 899, 

1041 

to multi byte character 
(from widecharacter), 
1061 

to tm structure 
1036-1037 

to unagned long integers 

1041-1042 
to widecharacter (from 
multibytej, 977-978 
copying, 498,1030-1031 
stpcpyf) function, 
1027-1028 

describing signals with, 1038 
duplicating, 1031 
extracting tokens from, 
1037-1040 

length (calculating), 1035 
locating characters in, 953, 
1029 

options, 498 
outputting, 997-999 
randomizing, 1032 
searching, for character sets, 
1035-1039 

string operation functions, 
1034-1035 

transformation, 1042-1043 
see a/so substrings 

strip, 499 

strlen() function, 1035 
strncasecmp(), 1028 
strncat() function, 1028-1029 
strncmp() function, 

1029- 1030 
strncpyt) function, 

1030- 1031 
strpbrk() function, 

1035- 1036 
strptime() function, 

1036- 1037 
bugs, 1037 

field descriptors, 1036-1037 

strrchr() function, 1029 
strsep() function, 1037-1038 
strsignal() function, 1038 
strspn() function, 1038-1039 


strstr() function, 1039 
strtod() function, 1039-1040 
strtok() function, 1040 
strtol() function, 1041 
strtoul() function, 1041-1042 
struct (ftp command), 152 
strxfrm() function, 

1042-1043 

subdirectories, MS-DOS 

creating, 326 
moving, 327 
removing, 329 
renaming, 329-330 
subroutines 

endnetent, 936-937 
getnetbyaddr, 936-937 
getnetbyname, 936-937 
getnetent, 936-937 
subst, 500-501 
substrings 
locating, 1039 
locating in memory areas, 
981 

seea/so strings 

suffixes, 1249-1252 
sum, 501 

Sun icons, converting to 
portable bitmaps, 262 
Sun raster files, converting to 
portable anymaps, 438 
SuperProbe, 501-503 
bugs, 503 
options, 502 
running, 502-503 
suspend (shell command), 
42-43 

suspending execution, 1061 
swab() function, 1043 
swap area, settingup, 
1327-1328 

swap device parameter, values, 
1374 

swapoff, 866-867,1401 

errors, 867 
files, 1401 
priority, 867 


swapon, 866-867,1401 

errors, 867 
files, 1401 
priority, 867 

swapping 

enabling/disabling, 1401 
starting/stopping, 866-867 
priority, 867 

swapping bytes, 1043 
symbolic links, 867-869 
reading values, 823-824 
symlink, 867-869 
sync, 869,1401-1402 
synchronizing files with 
memory maps, 811 
synchronous I/O, 
multiplexing, 835-837 
syscall macros, 738 
syscall() macros, 738 
sysconff) function, 

1043-1045 
sysctl, 869-871 
sysfs, 871 
sysinfo, 871-872 
sysklogd, 1402-1404 
configuration file, 1402- 
1403 

FIFOs, 1403 
files, 1404 
installing, 1403 
remote logging, 1403 
security, 1403-1404 
syslog, 872-874 
syslog() function, 1045-1046 
syslog.conf, 1186-1188 
action field, 1186-1187 
examples, 1187-1188 
facility keyword, 1187 
level keyword, 1187 
selector field, 1186-1187 
syslogd, 1404-1405 
configuration file, 1186- 
1188 

action field, 1186-1187 
examples 1187-1188 
fad lity keyword, 1187 
level keyword, 1187 
selector field, 1186-1187 
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files, 1405 
options, 1405 

system 

configuration, getting 
information at runtime, 
1043-1045 

displaying information 
about, 562 

load average graphing, 533 
page size, getting, 765 
parameters, reading/writing, 
869-871 

printing activity summary, 
573 

shutting down, 1396-1397 
state, updating, 1414-1415 
status server, 1386-1387 
message format, 
1386-1387 

system (ftp command), 152 
system calls, 738-739 

calling directly, 738 
interrupting with signals, 
1019 
IPC,789 
obsolete, 814 
prototypes, 738 
socket, 862 
syscall macros, 738 
undocumented, 881 
unimplemented, 881-882 
system logging, 1402-1404 
configuration file, 
1402-1403 
FIFOs, 1403 

making log entries, 295-296 
messages, 1404-1405 
remote, 1403 
sending messages to, 
1045-1046 

System V interprocess 
communication, 1144-1146 

message queues, 1145 
resource access permissions, 
1144-1145 

semaphore sets, 1145-1146 
shared memory segments, 
1146 


System V I PC keys, convert¬ 
ing pathnames/project 
identifiers to, 929-930 
system!) function, 1047 
sysv filesystem, 1125 


Tab W indow M anager, see 
twm 
tables 

descriptor, size (getting), 
760-761 
file 

adding entries 
1428-1429 

description, 1425-1426 
initializing, 1427 
moving files to end, 1431 
removing files 1431-1432 
irudure, 1426 
table entries 1426 
unrderenced entries 
(fetching), 1428 
hash 

creating, 951 
freeing memory, 951 
searching, 951 
IP routing (manipulating), 
1379-1380 

local descriptor, reading/ 
writing, 800 

RARP, manipulating, 1373 
troff, formatting, 236-237 

tabs, converting to spaces, 137 
tac, 503-504 

tag (cvs command), 102-103 
tag files 

emacs, 135-137 
generating, 87-88 
vi, 135-137 
tail, 504 
talk, 505 
talkd, 1405-1406 
tan() function, 1047-1048 
tanh() function, 1048 
teal, 506 


tcdrain(), 876,1052 
tcflow(), 876,1052 
teflushf), 876,1052 
tegetattrf), 876,1051 
tcgetpgrpf), 877,1053 
tcsendbreak(), 876,1052 
tesetattrf), 876,1052 
tcsetpgrp(), 877,1053 
tdelete, 1056-1058 
tek-copy() action (xterm), 

716 

tek-page() action (xterm), 

715 

tek-reset() action (xterm), 

716 

tel in it, 1307-1309 

diagnostics, 1309 
files, 1308 
run levels, 1308 

telldir() function, 1048 
telnet, 507-512 

commands, 508-512 
512 
7,512 
dost 508 

display argument, 508 
environ, 511 
mode 508 
open hoi, 508 
quit, 508 

send arguments 508-509 

st, 509-510 

ic, 510 

iatus 512 

toggle, 511-512 

unsi, 509-510 

z,512 

environment, 512 
files, 512 
options, 507 

Telnet protocol 

DARPA server, 1406-1407 
interface, see tel net 

telnetd, 1406-1407 
tempnam() function, 1049 
temporary filenames, creating, 
983-984 
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temporary files 

creating, 983,1053-1054 
naming, 1049,1054 
tenex (ftp command), 152 
termcap, 1188-1197 

Boolean capabilities, 1189 
numeric capabilities, 

1189- 1190 
string capabilities, 

1190- 1197 

control codes 1195-1196 

terminals 

attributes, 1049-1053 
getting 876 
setting, 482-483, 876 
baud rate 1049-1053 
capability database, 

1188-1197 

Boolean capabilities 1189 
numeric capabilities 

1189- 1190 
string capabilities 

1190- 1197 
controlling terminal, 

1100-1101 
creating typescript of 
sessions, 474-475 
displaying last login, 
285-286 

foreground processes, group 
ID, 1049-1053 
initializing, 539-542 
line control, 1049-1053 
name and de/ice list, 1197 
names (returning), 1058 
resetting, 456 
serial lines, 1101 
termiosfunctions, 874-878 
type mapping, 540-541 
type setting in shell 
environment, 540 
virtual hangups, 885 
window size, setting, 
456-457 

terminating processes, 
283-284 


terminating programs 

abort() function, 892 
assert)) function, 895-896 
termios functions, 874 
flag constants, 874-876 
termios structure 

c cflag flag constants, 1051 
cjflag flag constants, 1050 
c_lflag flag constants, 1051 
c_oflag flag constants, 
1050-1051 

testexpr (shell command), 43 
text 

compressed, viewing, 
733-734 

filters, more, 327-328 
formatting line lengths, 143 
rendering to bitmaps, 
355-356 
sorting, 492-493 
editors, elvis, 126-128 
files 

converting for printing, 
429-430 

creating gcal resource files 
from, 558 

tfind, 1056-1058 
tfmtodit, 513 

TFTP (Trivial FileTransfer 
Protocol), 1407 

DARPA server, 1407 

tftp, 514-515 

TFTP (Trivial FileTransfer 
Protocol), 514 
tftpd, 1407 
tgatoppm, 515 
TI ACTIVEFILE environ¬ 
ment variable, 529 
TI_NOVROOTDIR environ¬ 
ment variable, 529 
TIFF files, converting to 
portable anymaps, 515-516 
tifftopnm, 515-516 
tilde expansion (bash), 19 
time 

calculating differences, 911 
getting/setting, 772-773 
in seconds 878 


returning current, 928-929 

setting, 866 

startup 

adjuring to GMT, 
1424-1425 
converting, 1430 

time functions, 878 

awk, 169 

time server daemon, 
1407-1408 
time zones 

compiling, 1419-1422 
printing, 1419 

time-sharing scheduling, 834 
timed, 1407-1409 

control program, 1408-1409 
files, 1408 
timedc, 1408-1409 
timers (event), managing, 
1424 
times 

binary, converting to ASC11, 
909-911 
converting 

to ASCII, 984-986 
initializing converson 
information, 986-988, 
1058-1060 
irings to numbers 
989-990 
to tm structure 
1036-1037 
formatting, strftime() 
function, 1032-1034 
process, getting, 878-879 
time zone information files, 
1197-1198 

user/system, printing, 43 

times (shell command), 43 
times function, 878-879 
timestamps, changing, 536 
tin, 516-533 

articles 

automatic mailing, 528 
autoselect/autokill, 
526-527 
crosspoiing, 527 
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customizing quote string, 
527 

mailing, 527 
piping, 527 
poking, 527 
printing, 527 
saving, 527-528 
tagging/un tagging, 528 
bugs, 531 
commands 

article viewer, 522-524 
editing, 519 

global options menu, 524- 
525 

group index, 521-522 
newsgroup selection, 
519-520 

pool directory selection, 
520 

thread listing 522 
environment variables, 
528-530 

ADD_ADDRESS, 529 
AUTOSUBSCRIBE, 529 
AUTOUNSUBSCRIBE, 
530 

BUG_ADDRESS, 529 
DISTRIBUTION, 529 
MAILER, 529 
NNTPSERVER, 529 
ORGANIZATION, 529 
REPLYTO,529 
TI_ACTIVEFILE, 529 
TI NOVROOTDIR, 529 
TIN_HOMEDIR, 528 
TIN INDEXDIR, 529 
TIN-LIBDIR, 529 
TIN SPOOLDIR, 529 
TINRC, 528 
VISUAL, 529 
files, 531 

group attributes, 526 
index files, 517-518 
moving between levels, 519 
news administration, 518 
options 516-517 
screen format, 518-519 


signatures, 528 
starting, 518 

tinrc configurable variables, 
525-526 

xterm buttons, 530-531 

TINHOMEDIR 
environment variable, 528 
TINJNDEXDIR 
environment variable, 529 
TIN LIBDIR environment 
variable, 529 
TIN_SPOOLDIR 
environment variable, 529 
tinrc configurable variables, 
525-526 
see a/so tin 

TINRC environment variable, 
528 

tload, 533 

TM OUT variable (bash), 17 
/tmp directory, 1237 
tmpfile() function, 

1053-1054 

tmpnam() function, 1054 
toascii() function, 1055 
toggle command (telnet), 
511-512 

tokens, extracting from 
strings, 1037-1040 
tolower() function, 

1055-1056 
top, 533-535 
bugs 535 

commands 534-535 
field descriptions, 534 
options 534 

topological sorting (graphs), 
542 

touch, 536 
toupper() function, 
1055-1056 
tr, 536-539 

character classes, 537-538 
escape characters, 537 
ranges, 537 

repeated characters, 537 
specifying character sets, 537 


squeezing/deleting, 538-539 
translating, 538 
warning messages, 539 

tr2tex, 1252-1253 
trace (ftp command), 152 
traceroute, 1409-1412 
examples, 1411 
options 1410 
transforming strings 
1042-1043 

translating/deleting charac¬ 
ters, 536-539 

trap (shell command), 43-44 
Trivial File Transfer Protocol, 
seeTFTP 
troff 

compiling pictures for, 
211-215 

converting to LaTeX, 
1252-1253 

formatting tables, 236-237 
output format, 1129-1131 

T rueVision T arga fi les 
converting to portable 
pixmaps, 515 
truncate, 879-880 
tryaffix, 274, 281 
files, 281 
seea/so ispell 
tsearch, 1056-1058 
tset, 539-542 
compatibility, 542 
environment, 541 
files, 541 
options 540 

setting environment, 540 
terminal type mapping, 
540-541 

tsort, 542 
tty, 1100-1101 
ttyname, 1058 
ttys, 1101 
ttytype, 1197 
tune2fs 1412-1413 
tuneip, 1413-1414 
twalk, 1056-1058 
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twm, 542-557 

bindings, 552-553 
bugs, 557 

customizing, 543-544 
environment, 557 
files, 557 

functions, 554-556 
1 554 

f.autoraisa, 554 
f. backiconmgr, 554 
f.beep, 554 
f.bottomzoom, 554 
f.drcledown, 554 
f.drcleup, 554 
f.colormap, 554 
f.deiconify, 554 
f. delete 554 
f.ddtastop, 554 
f.destroy, 554 
f.downiconmgr, 554 
f.exec, 554 
f. focus 554 
f.forcemove 555 
f.forwiconmgr, 555 
f. full zoom, 555 
f. function, 555 
f.hbzoom, 555 
f.hideiconmgr, 555 
f.horizoom, 555 
f.htzoom, 555 
f.hzoom, 555 
ticonify, 555 
f. identify, 555 
f.lefticonmgr, 555 
f.leftzoom, 555 
flower, 555 
f.menu, 555 
f.move, 555 
f.necticonmgr, 555 
f.nop, 555 
f.previconmgr, 555 
f.priority, 555 
f.quit, 555 
f. raise 555 
f. raise! ower, 555 
f. refresh, 555 
f.resze, 555 


f. restart, 555 
f.rightieonmgr, 555 
f.rightzoom, 556 
f.saveyourself, 556 
f.diowioonmgr, 556 
f. sard con mgr, 556 
f. title, 556 
f.topzoom, 556 
f. unfocus 556 
f.upiconmgr, 556 
f.vlzoom, 556 
f.vrzoom, 556 
f. warpring, 556 
f.warpto, 556 
f.warptoiconmgr, 556 
f.warptosjesn, 556 
f.winrefresh, 556 
f.zoom, 556 
icons, 557 
menus, 556-557 
options, 543 
starting, 543 
startup files, 543-544 
variables, 544-552 
AutoRaise 544 
AutoRelativeResize 

544-545 
BorderColor, 545 
BorderT ileBackground, 

545 

BorderT ileForeground, 

545 

BorderWidth, 545 
Buttonlndent, 545 
ClientBorderWidth, 545 
Color, 545-546 
ConstrainedM oveT ime, 

546 

Cursors 546 
DecorateT ransients 546 
DefaultBackground, 546 
DefaultForeground, 547 
D efaultFunction, 552 
D ontlconifyByU nmapping 

547 

DontMoveOff, 547 
D ontSqueezeTitle 547 


Forcelcons 547 
FramePadding, 547 
Grayscale 547 
IconBackground, 547 
I con BorderCol or, 547 
IconBorderWidth, 547 
IconD irectory, 547 
IconFont, 547 
IconForeground, 547 
IconifyByU nmapping, 
547 

IconM anagerBackground, 
547 

IconM anagerD ontShow, 

547 

IconM anagerFont, 548 
IconM anagerForeground, 

548 

IconM anagerG eometry, 
548 

IconM anagerH /gW/gfit, 

548 

IconM anagers 548 
IconM anagerShow, 548 
IconRegion, 548 
Icons 548-549 
InterpolateMenuColors 

549 

M akeT itle, 549 
M axW indowSize 549 
MenuBackground, 549 
MenuFont, 549 
M enuForeground, 549 
MenuShadowColor, 549 
M enuT itleBackground, 
549 

M enuT itleForeground, 
549 

M onochrome, 549 
MoveDelta, 549 
NoBackingStore 549 
NoCassSensitive, 549 
N oD efaults 549 
NoGrabServer, 549 
N oH ighlight, 550 
NolconM anagers 550 
N oM enuShadows 550 
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N oRaissO nD eiconify, 550 
NoRaisaOnM ove 550 
N oRaissO nResze, 550 
NoRaiseOnWarp, 550 
NoSavdUnders 550 
N oStadkM ode, 550 
NoTitle 550 
N oT itleFocus 550 
N oT itletl ighlight, 550 
OpaqueM ove, 550 
Pixmaps 550 
Priority, 550 
RandomPlacement, 550 
ReazeFont, 551 
RestartPreviousState 551 
SavdOolor, 551 
ShowiconM anager, 551 
SortlconM anager, 551 
SqueezeTitle 551 
Start! coni tied, 551 
TitleBackground, 551 
T itteButtonBorderW idth, 
551 

TitleFont, 552 
T itleForeground, 552 
TitleP adding, 552 
Unknown!con, 552 
U sSP Position, 552 
WarpCursor, 552 
WarpUnmapped, 552 
WindowF unction, 552 
WindowRing 552 
XorValue 552 
Zoom, 552 
windows, 543 
creating, 543 
resizing, 543 
txt2gcal, 558 
type 

ftp command, 152 
shell command, 44 

TZ environment variable, 987 
tzfile, 1197-1198 
tzset, 986-988 

files, 988 

TZ environment variable, 
987 

tzset() function, 1058-1060 


u 


UID variable (bash), 15 
ul, 558-559 

ulimit (shell command), 

44-45 
umask, 880 

ftp command, 152 
shell command, 45 
umsdos filesystem, 1125 
unalias (shell command), 45 
uname, 880-881 
unbuffered streams, 1016 
underlining, 558-559 
underscores! ), bash special 
parameters, 15 
undocumented system calls, 
881 

unexpand, 559 
ungetc() function, 945 
Unicode, 1065,1253-1255 

ASC11 -compatible encoding, 
1255-1256 

combining characters, 1254 
implementation levels, 1254 
Website, 1065 

unimplemented system calls, 
881-882 
uniq, 560 

Universal Product Code 
bitmaps, creating, 368 
UNIX 

copying MS-DOS files to/ 
from, 317-318 
filenames, restoring, 

324-325 
files, copying 

between ystems 563-565 
to MS-DOS, 335 
unlink, 882 
unlocking memory 
munlock, 811-812 
munlockall, 812-813 
unmapping files to memory, 
799-800 


unmount, 802-804, 
1328-1332 

bugs, 1332 
errors, 803 
files, 1332 
options, 1331 
return value, 803 
unset 

shell command, 45 
telnet command, 509-510 

unshar, 560-561 
unsq, 496 

update (cvs command), 
103-104 

update state* 1414-1415 
updatedb, 561-562 
uppercase, converting letters 
to, 1055-1056 
uptime, 562 
uselib, 883 
Usenet 

administration, 1344-1346 
archiver, 1262-1263 
articles 

expiring, 1121-1123 
libinn routines, 962-966 
purgng, 1292-1293 
record of, 1131-1132 
retria/ing fro N NT P 
server, 340-341 
sending to remote NN TP 
server, 1312-1313 
sanding to remote site 
1349-1350 
specifying distribution, 
1158-1163 

batch files, converting to 
INN, 1281-1282 
control messages, handling, 
1115-1116 
databases, recovering, 
1342-1344 
history file 

diqolaying filenames from, 
226-227 

removing filenames 
1370-1371 
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innwatch supervision, 
1142-1144 
log files, 1163-1165 
Hi of, 1164 

maintenance 1346-1347 
message/action fields 
1163-1164 

moderated newsgroups, mail 
addresses, 1151-1152 
newsgroups, listing active, 
1104-1105 

sending articles to servers, 
267-269 

UsenixFaceSaver files, 
converting to portable 
graymaps, 147 
user (ftp command), 152 
user group file, 1131 
user ID s (processes), setting, 
848-849 

real and effective, 847-848 

userlist, 563 
usernames 

getting, 934-935 
remote lookup, 1134-1135 

users 

adding to system, 

1258-1259 
displaying last login, 
285-286 

file permissions, checking, 
741-742 
IDs, getting, 773 
listing, 563 

logins, preventing, 1168 
outputting logged in 
on local machines 474 
on networks 472-473 
preference utility (X), 
690-693 

printing activity summary 
(w), 573 

quotas, editing, 1291-1292 
sending messages to, 473, 
576-577 

shells, getting, 946-947 
switching between, 296 


talking to online^ 505 
writing messages to, 574, 
1383 

usleep( (function, 1061 
/usr directory, 1237 
/usr/XHR6 directory, 1237 
/usr/XHR6/bin directory, 
1237 

/usr/XHR6/lib directory, 

1237 

/usr/XHR6/lib/Xll directory, 
1237 

/usrXHR6/indude/Xll 
directory, 1237 
ustat, 883-884 
UTF-8,1255-1256 
examples, 1256 
properties, 1255-1256 
utime, 884-885 
utimes, 884-885 
utmp, 1198-1200 
utmp file entries, accessi ng, 
947-948 

utmp/wtmp entries, manag¬ 
ing, 480-481 

utmpname() function, 947 
uucico, 1415-1417 

files, 1416-1417 
options, 1415-1416 

UUCP, 563-565 

bugs, 565 

execution daemon, 572 
files, 564-565 
options, 564 

remote command execution, 
569-571 

status inquiry, 566-569 

UUCP 

connections, receiving news, 
463-464 

file transfer requests, 
processing, 1415-1417 

uudecode, 565-566 
uuencode, 565-566,1200 
uustat, 566-569 

examples, 568-569 
files, 569 
options, 567-568 


uux, 569-571 

bugs, 571 
examples, 571 
files, 571 
options, 570-571 
restrictions, 571 
uuxqt, 572 

V 


variable argument lists 
(declaring), 1023-1024 
variables 

awk, 163-165 
arrays 164 
built-in, 163-164 
typing and conversion, 
164-165 
bash, 15-18 
allow-null_$ob 
_expansion, 17 
autojesjme, 18 
BASH,15 

BASH _VERSION, 15 
cdable_vars 18 
CDPATH,16 
command_ oriented_ hi dory, 

17 

EN V, 16 
EUID.15 
FCEDIT, 17 
FIGNORE, 17 
gtob_dot_filenames 17 
hi debars 17-18 
HISTCMD, 16 
HISTFILE, 17 
HISTFILESIZE, 17 
HIST SIZE, 17 
HOME, 16 

hodname_ completion_ file 

18 

HOSTTYPE, 16 
IFS, 16 

IGNOREEOF, 17 
INPUTRC, 17 
LINENO, 15 
MAIL, 16 
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MAIL_WARNING, 16 
MAILCHECK, 16 
MAILPATH, 16 
no_ exi t_ on_ failed_ exec, 

18 

noclobber, 18 
nolinks 18 
notify, 17 
OLDPWD, 15 
OPTARG,16 
OPTERR, 17 
OPTIND, 16 
0 STY PE, 16 
PATH, 16 
PPID, 15-17 
PROM PT_COMM AND, 
17 

PS1,16 
PS2,16 
PS3,17 
PS4,17 
PWD, 15 
RANDOM, 15 
REPLY, 15 
SECONDS, 15 
SHLVL, 15 
TM0UT,17 
UID.15 
declaring, 36 
local, creating, 39 
readline, 28 
bell-style, 28 
comment-begin, 28 
completion-query-items 
28 

convert-mdta, 28 
editing-mode 28 
expand-tilde, 28 
horizontal-scroll-mode 28 
keymap, 28 

mark-modified-lines 28 
meta-flag, 28 
output-meta, 28 
diow-all-if-ambiguous 28 
string, configuration- 
dependent, 906-907 


vcs, 1101-1102 
vcsa, 1101-1102 
vectors, reading/writing, 
824-825 

verbose (ftp command), 152 
vfat filesystem, 1125 

case sensitivity (mtools and), 
332 

vfork, 758 

vfprintf function, 992-996 
vfscanf function, 1013-1015 
vhangup, 885 
vi, see el vis 

video hardware, identifying, 
501-503 

video mode tuner (XFree86), 
719-720 
buttons, 719 
moving display, 719 
options, 720 
vidr, 303-304 
view, see el vis 
vipw, 1418-1419 
virtual 8086 mode, entering, 
885-886 

virtual consoles, 1066 

memory, 1101-1102 

virtual framebuffer X server, 
717-718 
virtual memory 

addresses, remapping, 
805-806 

reports, 1417-1418 

VISUAL environment 
variable, 529 

visual-bell() action (xterm), 
716 

vm86, 885-886 
vmstat, 1417-1418 
volume labels (MS-DOS), 
creating, 325-326 
vprintf function, 992-996 
vscanf function, 1013-1015 
vsnprintf function, 992-996 
vsprintf function, 992-996 
vsscanf function, 1013-1015 


w 


w, 573 

wait, 886-888 
errors, 887 
shell command, 45 
status macros, 887 

wait3, 888-889 
wait4, 888-889 
waitpid, 886-888 
wail, 574 
wc, 574 

wcstomb() function, 
1061-1062 

wcstombs() function, 1061 
Web sites, Unicode, 1065 
whereis, 575-576 
while (bash command), 13 
wide character stri ngs, 
converting to multi byte 
character strings, 1061 
wide characters, converting to 
multibyte characters, 
1061-1062 
widgets 

bitmap application, 54-57 
editres, 125-126 
xdipboard, 596 
xdock, 595 
xconsole, 598 
xcutsel, 599 

xdm authentication widget, 
609-610 

actionssupported, 610 
resources 609-610 
xfd, 634-635 
xlogo, 668 
xmag, 671 
windows; X 

dumping utility, 721-722 
information utility, 722-724 

word splitting (bash), 21 
words 

bash, 12 

finding first bit set, 921 
input/output, 948 



Xll bitmaps converting to portable ■ 


wrapping input lines, 143-144 
write, 576-577, 889-890 

errors, 889-890 

writev, 824-825,1003-1004 

bugs, 1004 
errors, 825,1004 

wtmp, 1198-1200 

X 


X Color M anagement System, 
D evice C olor C haracteriza- 
tion utility, 592-593 
X commands, grops, 232-233 
X font servers 

displaying information 
about, 145 

generating BDF fonts, 
146-147 

listing fonts, 145-146 

X sessions, initializing, 
496-497 

X Window System 

clients 

clipboard dient, 595-597 
listing applications 
669-670 
clock, 593-595 
D isplay M anager, 599-614 
authentication widget, 
609-610 
chooser, 607 
configuration file 606 
controlling, 613 
environment variables 
608 

files 613 
limitations 613 
local server spedfication, 
607-608 
options 600-601 
reset program, 612 
resources 601-606 
resources file 608 
server control, 612-613 
session program, 611-612 
sessions 600 


setup program, 608-609 
startup program, 610-611 
XDMCP service access 
control, 606-607 
emacs, 131-132 
fonts 

digolaying all characters 
in, 633-636 
listing, 670-671 
image displayer, 725-726 
environment, 726 
options 725-726 
imak$ 266 
initializer, 664-666 
keymaps, modifying, 
672-676 

LBX proxy server, 286-287 
logo, 667-668 
magnifying screen, 671-672 
monitoring system console 
messages, 597-598 
property displayer, 677-681 
constructing formats 679 
examples 680 
format characters 679 
Ceding windows 678 
remote program starts, 676 
resource database utility, 
681-684 

files/mbols 681-682 
options 682-684 
root window parameters 
(setting), 693-694 
screen, refreshing, 684-685 
server information utility, 
614 
servers 

access control program, 
643-645 

digolay server, 685-690 
fontserver, 641-643 
killing dients 666-667 
virtual framebuffer, 
717-718 

XFree86, 636-641 
Session M anager, 694-698 
ddault startup applica¬ 


tions 695 
options 695-698 
proxy, 698 

remote applications 698 
Session menu, 695-696 
SM SAVE DIR 
environment variable 
695 

darting sessons 695 
tester, 698-699 
.xsesaon file, 695 
standard colormap utility, 
699-700 

T ab W indow M anager, 
542-557 

bindings 552-553 
bugs 557 

customizing, 543-544 
functions 554-556 
icons 557 
menus 556-557 
options 543 
starting, 543 
startup files 543-544 
variables 544-552 
windows 543 

terminal emulator, 700-717 
actions 713-716 
character classes 712-713 
emulations 700 
environment, 717 
features 700-701 
menus 711-712 
options 701-705 
pointer usage, 710-711 
resources 705-710 
security, 712 
user preference utility, 
690-693 

window dumping utility, 

721- 722 

window information utility, 

722- 724 

X10 bitmaps, converting to 
portable, 592 

Xll bitmaps, converting to 
portable, 592 



■ Xll pixmaps converting to portable 


Xll pixmaps, converting to 
portable, 677 
Xll server 

performance comparison 
program, 585-586 
performance test program, 
577-585 

X11/X10 window dump files, 
converting to portable 
anymaps, 722 
xllperf, 577-585 
options, 578-585 
xllperfcomp, 585-586 
xargs, 586-587 
xauth, 587-592 
bugs, 592 

commands, 588, 591 
?,591 
exit, 591 
help, 591 
info, 591 
lit, 591 
merge, 591 
quit, 591 
remove, 591 
source 591 
display names, 591 
environment, 589 
environment variables, 592 
example, 591 
files, 589, 592 
generating magic cookies 
for, 317 

options, 587-588 

xbmtopbm, 592 
xdipboard, 595-597 

buttons, 596 
environment, 597 
files, 597 
options, 596 

sending/retrieving contents, 
596-597 
widgets, 596 
xdock, 593-595 
bugs, 595 
defaults, 594-595 
environment, 595 


files, 595 
options, 594 
widgets, 595 

xcmsdb, 592-593 
xconsole* 597-598 
xcutsel, 598-599 
Xdf disks, 332 
xdm, 599-614 

authentication widget, 
609-610 

adions supported, 610 
resources 609-610 
chooser, 607 
configuration file, 606 
controlling, 613 
environment variables, 608 
files, 613 
limitations, 613 
local server specification, 
607-608 

options, 600-601 
reset program, 612 
resources, 601-606 
D iqolayM anager., 604 
D ispiayM anager. accesf He 
603 

D ispiayM anager. authD ir, 
602 

D iqoiayM anager.autoResan, 
602 

D is j/ayM anage.didcer imeout 
603 

D iplayM anagr.daenonM ode 
602 

D iqolayM anager. debud- evef, 
602 

D ispiayM anager. DISPLAY. 

authComplain, 605 
D ispiayM anager.D ISPLAY. 

authFile 605 
D ispiayM anager.D ISPLAY. 

authN ame 605 
D ispiayM anager.D ISPLAY. 

authorize 605 
D ispiayM anager.D ISPLAY. 
chooser, 603 


D ispiayM anager.D ISPLAY. 
cpp, 603 

D ispiayM anager.DISPLA Y. 

faiIsaf(Client, 605 
D ispiayM anager.D ISPLA Y. 

grabServer, 605 
D ispiayM anager.D ISPLA Y. 

grab! imeout, 605 
D ispiayM anager.D ISPLAY. 

openD day 604 
D ispiayM anager.D ISPLAY. 

open Repeat, 604 
D ispiayM anager.D ISPLAY. 

openT imeout, 604 
D ispiayM anager.D ISPLA Y. 

pinglnterval, 604 
D ispiayM anager.D ISPLA Y. 

pingT imeout, 604 
D ispiayM anager.D ISPLA Y. 
rest, 604 

D ispiayM anager.D ISPLAY. 

resdtForAuth, 606 
D ispiayM anager.D ISPLA Y. 

restSignal, 605 
D ispiayM anager.D ISPLAY. 

resources 603 
D ispiayM anager.D ISPLA Y. 
sssaon, 603 

D ispiayM anager.D ISPLA Y. 
setup, 603 

D ispiayM anager.D ISPLA Y. 
tartup, 603 

D ispiayM anager.D ISPLAY. 

9/iemPath, 604-605 
D ispiayM anager.D ISPLAY. 

sytemShell, 605 
D ispiayM anager.D ISPLAY. 

terminateServer, 604 
D ispiayM anager.D ISPLA Y. 

termSignal, 605 
D ispiayM anager.D ISPLA Y. 

user AuthD ir, 606 
D ispiayM anager.D ISPLA Y. 

userPath, 604 
D ispiayM anager.D ISPLAY. 
xrdb, 603 


xlogo ■ 


D iqrlayM anager.errorL of i let 
602 

D iqelayM anager.exportList, 
603 

D isplayM anager.greeterLib, 
603 

D iqelayM anager.keyFilg 
602 

D iqolayM anager.lockPidFile 
602 

D igolayM anager.pidFilet 
602 

D iqolayM anager.randcmFilet 
603 

D iqelayM anager.remove 
D omainname, 602 

D iqelayM anager.requestPort, 
601 

D iqelayM anager.servers 
601 

resources filev 608 
server control, 612-613 
session program, 611-612 
sessions, 600 
setup program, 608-609 
startup program, 610-611 
XDM CP service access 
control, 606-607 
XDM CP service, access 
control, 606-607 
xdpyinfo, 614 
XF86 8514 server, 615 
XF86_Accel, 614-623 
bugs, 623 

configuration, 615-616 
files, 622 
options, 616 
setup, 616-622 

XF86 AGX server, 615 
XF86 Mach32 server, 615 
XF86 Mach64 server, 615 
XF86 Mach8 server, 615 
XF86_Mono, 624-627 
configuration, 624 
files, 626 
options, 624 
setup, 624-626 


XF86 P9000 server, 615 
XF86~S3 server, 615 
XF86~SVGA, 627-631 

configuration, 627-628 
files, 630-631 
options, 628 
setup, 628-630 
XF86_VGA16, 631-633 
configuration, 631 
files, 633 
options, 632 
setup, 632 

XF86 W32 server, 615 
XF86Config, 1201-1208 

Device sections, 1204-1206 
Files section, 1201 
Keyboard section, 1202 
M onitor sections, 
1203-1204 

Pointer section, 1202-1203 
Screen sections, 1206-1208 
ServerFlags section, 1201 
xf86config, 633 
xfd, 633-636 

application-specific 
resources, 635 
bugs, 636 

fontgrid resources, 635 
options, 634 
widgets, 634-635 
XFree86, 636-641 
configuration, 636 
configuration file, 
1201-1208 
Device sections 1204- 
1206 

Filessection, 1201 
Ke/board section, 1202 
M onitor sections 
1203-1204 
Pointer section, 
1202-1203 
Screen sections 
1206-1208 

ServerFlags section, 1201 
environment variables, 637 
key combinations, 638 


network connections, 
636-637 

options, 637-638 
setup, 638 

video mode tuner, 719-720 
buttons 719 
moving display, 719 
options 720 

xfs, 641-643 

bugs, 643 
configuration, 642 
naming, 643 
options, 641 
signals, 641 
xhost, 643-645 
bugs, 644 
diagnostics, 644 
environment, 644 
files, 644 
names, 644 
options, 643-644 
xiafs filesystem, 1125 
XIE protocol, testing, 
645-654 
xieperf, 645-654 
bugs, 654 
options, 646-654 
XIM files, converting to 
portable pixmaps, 654 
ximtoppm, 654 
xinetd, 655-664 
bugs, 664 

configuration file, 656-660 
editing signal responses, 
660-661 
files, 663 

internal services, 660 
log format, 661-663 
options, 655-656 
xinit, 664-666 

environment variables, 666 
examples, 665-666 
files, 666 
xkill, 666-667 
xlogo, 667-668 

environment variables, 668 
resources, 668 
widgets, 668 


■ xlsatoms 


xlsatoms, 668-669 
xlsclients, 669-670 
xlsfonts, 670-671 
xmag, 671-672 
xmkmf, 672 
xmodmap, 672-676 
bugs, 675 
environment, 675 
examples, 674-675 
expression grammar, 
673-674 
options, 673 
xon, 676 
xpmtoppm, 677 
xprop, 677-681 

constructing formats, 679 
environment, 680 
examples, 680 
format characters, 679 
options, 677-678 
selecting windows, 678 
xrdb, 681-684 
bugs, 684 
environment, 684 
file symbols, 681-682 
options, 682-684 
xrefresh, 684-685 
arguments, 684-685 
bugs, 685 
defaults, 685 
environment, 685 
Xresourcesfile, 608 
X server, 685-690 
file utility, 587-592 
files, 690 
fonts, 689 
options, 686-687 

ndtwork connection s 688 
server-dependent, 
687-688 
XDMCP, 688 
XKEYBOARD, 688 
security, 688-689 
signals, 689 
starting, 685 


xset, 690-693 
xsetroot, 693-694 
xsm, 694-698 

default startup applications, 
695 

options, 695-698 
proxy, 698 

remote applications, 698 
Session menu, 695-696 
SM _SAVE_D IR environ¬ 
ment variable, 695 
starting sessions, 695 
tester, 698-699 
.xsession file, 695 
xsmclient, 698-699 
xstdcmap, 699-700 
xterm, 700-717 
actions, 713-716 

allow-send-events[), 7 14 
belli), 713 

dear-saved-linesl), 715 
hard-reset(), 715 
ignorel), 713 
insertl), 713 
inssrt-eight-bit(), 713 
insert-selection(), 713 
insert-sa/en-bit(), 713 
kymapl), 713 
popup-menuf), 713 
quitf), 714 
redrawf), 714 
sjoll-backl), 714 
s:roll-forw(), 714 
securel), 713 
select-cursor-end, 714 
select-cursor-startl), 714 
stledt-endl), 714 
seled-extendl), 714 
select-startl), 714 
send-sgnal(), 714 
set-allowl32(), 715 
sdt-altzreenl), 715 
sst-appcursor(), 715 
set-appkeypadf), 715 


sst-autolinefeed(), 715 
set-autowrapl), 715 
sst-cursesemul(), 715 
set-jumpsjolll), 715 
sst-margnbell(), 715 
set-reverse-videol), 715 
sti-reversewrapl), 715 
sdt-sjoll-on-key(), 715 
sst-scroll-on-tty-output(), 
715 

set-sjollbarl), 715 
sst-tek-text(), 715 
set-terminal-type(), 715 
set-vi s'bi I ity(), 715 
s£-visjal-bdl(), 715 
set-vt-font(), 714 
soft-resetl), 715 
start-airsor-extendl), 714 
start-extendl), 714 
dtringl), 714 
tek-copy(), 716 
tek-page(), 715 
tek-resrt), 716 
visual-bell(), 716 
bugs, 717 

character classes, 712-713 
emulations, 700 
environment, 717 
features, 700-701 
menus 711-712 
options, 701-705 
pointer usage 710-711 
resources, 705-710 
fontM enu entries 710 
mainMenu entries 709 
tekM enu entries 710 
vtMenu entries 709-710 
security, 712 
XV thumbnail pictures, 
converting to portable 
pixmaps, 720 
Xvfb, 717-718 
xvidtune, 719-720 
xvminitoppm, 720 


znew 


xwd, 721-722 
xwdtopnm, 722 


zic, 1419-1422 

files, 1422 

link lines, 1421-1422 
options, 1419-1420 
rule lines, 1420-1421 
zone lines, 1421 


xwininfo, 722-724 
xwud, 725-726 


Y 


y0() function, 959 


zmore, 733-734 
znew, 734-735 


yl() function, 959 
ybmtopbm, 726 
yn() function, 959 
ytalk, 727-730 

Boolean options, 729 
daemons, 727 
escape menu, 728 
files, 730 
readdressing, 729 
runtime options, 728-729 
startup file 729 
usernamefield, 727 
Xll interface, 730 
YU V bytes, converting to 
portable pixmaps, 731 
YUV files, converting to 
portable pixmaps, 730-731 
yuvplittoppm, 730-731 
yuvtoppm, 731 


z 


z command (telnet), 512 
Z files, recompressingtoGZ, 
734-735 
zcat, 248-249 
see a/sD gzi p 
zcatgzip, 248-249 
see a/sD gzi p 
zcmp, 731-732 
zdiff, 731-732 
zdump, 1419 

Zeissconfocal files, converting 
to portable anymaps, 732 
zeisstopnm, 732 
zero, 1094 
zforce, 732-733 
zgrep, 733 




